home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / djgpp / src / gcc-263 / invoke.tex < prev    next >
Encoding:
Text File  |  1994-11-03  |  159.6 KB  |  4,208 lines

  1. @c Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation, Inc.
  2. @c This is part of the GCC manual.
  3. @c For copying conditions, see the file gcc.texi.
  4.  
  5. @node Invoking GCC
  6. @chapter GNU CC Command Options
  7. @cindex GNU CC command options
  8. @cindex command options
  9. @cindex options, GNU CC command
  10.  
  11. When you invoke GNU CC, it normally does preprocessing, compilation,
  12. assembly and linking.  The ``overall options'' allow you to stop this
  13. process at an intermediate stage.  For example, the @samp{-c} option
  14. says not to run the linker.  Then the output consists of object files
  15. output by the assembler.
  16.  
  17. Other options are passed on to one stage of processing.  Some options
  18. control the preprocessor and others the compiler itself.  Yet other
  19. options control the assembler and linker; most of these are not
  20. documented here, since you rarely need to use any of them.
  21.  
  22. @cindex C compilation options
  23. Most of the command line options that you can use with GNU CC are useful
  24. for C programs; when an option is only useful with another language
  25. (usually C++), the explanation says so explicitly.  If the description
  26. for a particular option does not mention a source language, you can use
  27. that option with all supported languages.
  28.  
  29. @cindex C++ compilation options
  30. @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
  31. options for compiling C++ programs.
  32.  
  33. @cindex grouping options
  34. @cindex options, grouping
  35. The @code{gcc} program accepts options and file names as operands.  Many
  36. options have multiletter names; therefore multiple single-letter options
  37. may @emph{not} be grouped: @samp{-dr} is very different from @w{@samp{-d
  38. -r}}.
  39.  
  40. @cindex order of options
  41. @cindex options, order
  42. You can mix options and other arguments.  For the most part, the order
  43. you use doesn't matter.  Order does matter when you use several options
  44. of the same kind; for example, if you specify @samp{-L} more than once,
  45. the directories are searched in the order specified.
  46.  
  47. Many options have long names starting with @samp{-f} or with
  48. @samp{-W}---for example, @samp{-fforce-mem},
  49. @samp{-fstrength-reduce}, @samp{-Wformat} and so on.  Most of
  50. these have both positive and negative forms; the negative form of
  51. @samp{-ffoo} would be @samp{-fno-foo}.  This manual documents
  52. only one of these two forms, whichever one is not the default.
  53.  
  54. @menu
  55. * Option Summary::    Brief list of all options, without explanations.
  56. * Overall Options::     Controlling the kind of output:
  57.                         an executable, object files, assembler files,
  58.                         or preprocessed source.
  59. * Invoking G++::    Compiling C++ programs.
  60. * C Dialect Options::   Controlling the variant of C language compiled.
  61. * C++ Dialect Options:: Variations on C++.
  62. * Warning Options::     How picky should the compiler be?
  63. * Debugging Options::   Symbol tables, measurements, and debugging dumps.
  64. * Optimize Options::    How much optimization?
  65. * Preprocessor Options:: Controlling header files and macro definitions.
  66.                          Also, getting dependency information for Make.
  67. * Assembler Options::   Passing options to the assembler.
  68. * Link Options::        Specifying libraries and so on.
  69. * Directory Options::   Where to find header files and libraries.
  70.                         Where to find the compiler executable files.
  71. * Target Options::      Running a cross-compiler, or an old version of GNU CC.
  72. * Submodel Options::    Specifying minor hardware or convention variations,
  73.                         such as 68010 vs 68020.
  74. * Code Gen Options::    Specifying conventions for function calls, data layout
  75.                         and register usage.
  76. * Environment Variables:: Env vars that affect GNU CC.
  77. * Running Protoize::    Automatically adding or removing function prototypes.
  78. @end menu
  79.  
  80. @node Option Summary
  81. @section Option Summary
  82.  
  83. Here is a summary of all the options, grouped by type.  Explanations are
  84. in the following sections.
  85.  
  86. @table @emph
  87. @item Overall Options
  88. @xref{Overall Options,,Options Controlling the Kind of Output}.
  89. @smallexample
  90. -c  -S  -E  -o @var{file}  -pipe  -v  -x @var{language} 
  91. @end smallexample
  92.  
  93. @item C Language Options
  94. @xref{C Dialect Options,,Options Controlling C Dialect}.
  95. @smallexample
  96. -ansi  -fallow-single-precision -fcond-mismatch  -fno-asm
  97. -fno-builtin  -fsigned-bitfields  -fsigned-char 
  98. -funsigned-bitfields  -funsigned-char  -fwritable-strings
  99. -traditional  -traditional-cpp  -trigraphs
  100. @end smallexample
  101.  
  102. @item C++ Language Options
  103. @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
  104. @smallexample
  105. -fall-virtual  -fdollars-in-identifiers  -felide-constructors
  106. -fenum-int-equiv -fexternal-templates  -fhandle-signatures
  107. -fmemoize-lookups  -fno-default-inline  -fno-strict-prototype
  108. -fnonnull-objects  -fthis-is-variable  -nostdinc++
  109. -traditional  +e@var{n}
  110. @end smallexample
  111.  
  112. @item Warning Options
  113. @xref{Warning Options,,Options to Request or Suppress Warnings}.
  114. @smallexample
  115. -fsyntax-only  -pedantic  -pedantic-errors
  116. -w  -W  -Wall  -Waggregate-return  -Wbad-function-cast
  117. -Wcast-align -Wcast-qual  -Wchar-subscript  -Wcomment
  118. -Wconversion -Wenum-clash  -Werror  -Wformat
  119. -Wid-clash-@var{len}  -Wimplicit  -Wimport  -Winline
  120. -Wlarger-than-@var{len}  -Wmissing-declarations
  121. -Wmissing-prototypes  -Wnested-externs
  122. -Wno-import  -Woverloaded-virtual -Wparentheses
  123. -Wpointer-arith  -Wredundant-decls -Wreorder -Wreturn-type -Wshadow
  124. -Wstrict-prototypes  -Wswitch  -Wsynth  -Wtemplate-debugging
  125. -Wtraditional  -Wtrigraphs -Wuninitialized  -Wunused
  126. -Wwrite-strings
  127. @end smallexample
  128.  
  129. @item Debugging Options
  130. @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
  131. @smallexample
  132. -a  -d@var{letters}  -fpretend-float 
  133. -g  -g@var{level} -gcoff  -gdwarf  -gdwarf+
  134. -ggdb  -gstabs  -gstabs+  -gxcoff  -gxcoff+
  135. -p  -pg  -print-file-name=@var{library}  -print-libgcc-file-name
  136. -print-prog-name=@var{program}  -save-temps
  137. @end smallexample
  138.  
  139. @item Optimization Options
  140. @xref{Optimize Options,,Options that Control Optimization}.
  141. @smallexample
  142. -fcaller-saves  -fcse-follow-jumps  -fcse-skip-blocks
  143. -fdelayed-branch   -fexpensive-optimizations  
  144. -ffast-math  -ffloat-store  -fforce-addr  -fforce-mem
  145. -finline-functions  -fkeep-inline-functions  
  146. -fno-default-inline  -fno-defer-pop  -fno-function-cse
  147. -fno-inline  -fno-peephole  -fomit-frame-pointer  
  148. -frerun-cse-after-loop  -fschedule-insns  
  149. -fschedule-insns2  -fstrength-reduce  -fthread-jumps 
  150. -funroll-all-loops  -funroll-loops
  151. -O  -O0  -O1  -O2  -O3
  152. @end smallexample
  153.  
  154. @item Preprocessor Options
  155. @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
  156. @smallexample
  157. -A@var{question}(@var{answer})  -C  -dD  -dM  -dN
  158. -D@var{macro}@r{[}=@var{defn}@r{]}  -E  -H
  159. -idirafter @var{dir}
  160. -include @var{file}  -imacros @var{file}
  161. -iprefix @var{file}  -iwithprefix @var{dir}
  162. -iwithprefixbefore @var{dir}  -isystem @var{dir}
  163. -M  -MD  -MM  -MMD  -MG  -nostdinc  -P  -trigraphs
  164. -undef  -U@var{macro}  -Wp,@var{option}
  165. @end smallexample
  166.  
  167. @item Assembler Option
  168. @xref{Assembler Options,,Passing Options to the Assembler}.
  169. @smallexample
  170. -Wa,@var{option}
  171. @end smallexample
  172.  
  173. @item Linker Options
  174. @xref{Link Options,,Options for Linking}.
  175. @smallexample
  176. @var{object-file-name}
  177. -l@var{library}  -nostartfiles  -nostdlib  
  178. -s  -static  -shared  -symbolic  
  179. -Wl,@var{option}  -Xlinker @var{option}
  180. -u @var{symbol}
  181. @end smallexample
  182.  
  183. @item Directory Options
  184. @xref{Directory Options,,Options for Directory Search}.
  185. @smallexample
  186. -B@var{prefix}  -I@var{dir}  -I-  -L@var{dir}
  187. @end smallexample
  188.  
  189. @item Target Options
  190. @c I wrote this xref this way to avoid overfull hbox. -- rms
  191. @xref{Target Options}.
  192. @smallexample
  193. -b @var{machine}  -V @var{version}
  194. @end smallexample
  195.  
  196. @item Machine Dependent Options
  197. @xref{Submodel Options,,Hardware Models and Configurations}.
  198. @smallexample
  199. @emph{M680x0 Options}
  200. -m68000  -m68020  -m68020-40  -m68030  -m68040  -m68881  
  201. -mbitfield  -mc68000  -mc68020  -mfpa  -mnobitfield  
  202. -mrtd  -mshort  -msoft-float 
  203.  
  204. @emph{VAX Options}
  205. -mg  -mgnu  -munix
  206.  
  207. @emph{SPARC Options}
  208. -mapp-regs  -mcypress  -mepilogue  -mflat  -mfpu  -mhard-float
  209. -mhard-quad-float  -mno-app-regs  -mno-flat  -mno-fpu
  210. -mno-epilogue  -mno-unaligned-doubles
  211. -msoft-float  -msoft-quad-float
  212. -msparclite  -msupersparc  -munaligned-doubles  -mv8
  213.  
  214. SPARC V9 compilers support the following options
  215. in addition to the above:
  216.  
  217. -mmedlow  -mmedany
  218. -mint32  -mint64  -mlong32  -mlong64
  219. -mno-stack-bias  -mstack-bias
  220.  
  221. @emph{Convex Options}
  222. -mc1  -mc2  -mc32  -mc34  -mc38
  223. -margcount  -mnoargcount
  224. -mlong32  -mlong64
  225. -mvolatile-cache  -mvolatile-nocache
  226.  
  227. @emph{AMD29K Options} 
  228. -m29000  -m29050  -mbw  -mnbw  -mdw  -mndw
  229. -mlarge  -mnormal  -msmall
  230. -mkernel-registers  -mno-reuse-arg-regs
  231. -mno-stack-check  -mno-storem-bug
  232. -mreuse-arg-regs  -msoft-float  -mstack-check
  233. -mstorem-bug  -muser-registers
  234.  
  235. @emph{ARM Options}
  236. -mapcs -m2 -m3 -m6 -mbsd -mxopen -mno-symrename
  237.  
  238. @emph{M88K Options}
  239. -m88000  -m88100  -m88110  -mbig-pic  
  240. -mcheck-zero-division  -mhandle-large-shift 
  241. -midentify-revision  -mno-check-zero-division 
  242. -mno-ocs-debug-info  -mno-ocs-frame-position 
  243. -mno-optimize-arg-area  -mno-serialize-volatile
  244. -mno-underscores  -mocs-debug-info
  245. -mocs-frame-position  -moptimize-arg-area
  246. -mserialize-volatile  -mshort-data-@var{num}  -msvr3 
  247. -msvr4  -mtrap-large-shift  -muse-div-instruction 
  248. -mversion-03.00  -mwarn-passed-structs
  249.  
  250. @emph{RS/6000 Options and PowerPC}
  251. -mcpu=@var{cpu type}
  252. -mpower -mno-power -mpower2 -pno-power2
  253. -mpowerpc -mno-powerpc
  254. -mpowerpc-gpopt -mno-powerpc-gpopt
  255. -mpowerpc-gfxopt -mno-powerpc-gfxopt
  256. -mnew-mnemonics -mno-new-mnemonics
  257. -mfull-toc   -mminimal-toc  -mno-fop-in-toc  -mno-sum-in-toc
  258.  
  259. @emph{RT Options}
  260. -mcall-lib-mul  -mfp-arg-in-fpregs  -mfp-arg-in-gregs
  261. -mfull-fp-blocks  -mhc-struct-return  -min-line-mul
  262. -mminimum-fp-blocks  -mnohc-struct-return
  263.  
  264. @emph{MIPS Options}
  265. -mabicalls  -mcpu=@var{cpu  type}  -membedded-data
  266. -membedded-pic  -mfp32  -mfp64  -mgas  -mgp32  -mgp64
  267. -mgpopt  -mhalf-pic  -mhard-float  -mint64 -mips1
  268. -mips2 -mips3  -mlong64  -mlong-calls  -mmemcpy
  269. -mmips-as  -mmips-tfile  -mno-abicalls
  270. -mno-embedded-data  -mno-embedded-pic
  271. -mno-gpopt  -mno-long-calls
  272. -mno-memcpy  -mno-mips-tfile  -mno-rnames  -mno-stats
  273. -mrnames -msoft-float  
  274. -mstats  -G  @var{num}  -nocpp
  275.  
  276. @emph{i386 Options}
  277. -m486  -mieee-fp  -mno-486  -mno-fancy-math-387
  278. -mno-fp-ret-in-387  -msoft-float  -msvr3-shlib  
  279. -mno-wide-multiply -mreg-alloc=@var{list}
  280.  
  281. @emph{HPPA Options}
  282. -mdisable-fpregs  -mdisable-indexing  -mjump-in-delay 
  283. -mgas  -mlong-calls  -mno-disable-fpregs  -mno-disable-indexing
  284. -mno-gas  -mno-jump-in-delay
  285. -mno-long-calls  -mno-portable-runtime
  286. -mpa-risc-1-0  -mpa-risc-1-1  -mportable-runtime
  287.  
  288. @emph{Intel 960 Options}
  289. -m@var{cpu type}  -masm-compat  -mclean-linkage
  290. -mcode-align  -mcomplex-addr  -mleaf-procedures
  291. -mic-compat  -mic2.0-compat  -mic3.0-compat
  292. -mintel-asm  -mno-clean-linkage  -mno-code-align
  293. -mno-complex-addr  -mno-leaf-procedures
  294. -mno-old-align  -mno-strict-align  -mno-tail-call
  295. -mnumerics  -mold-align  -msoft-float  -mstrict-align
  296. -mtail-call
  297.  
  298. @emph{DEC Alpha Options}
  299. -mfp-regs  -mno-fp-regs  -mno-soft-float
  300. -msoft-float
  301.  
  302. @emph{Clipper Options}
  303. -mc300 -mc400
  304.  
  305. @emph{H8/300 Options}
  306. -mrelax  -mh
  307.  
  308. @emph{System V Options}
  309. -Qy  -Qn  -YP,@var{paths}  -Ym,@var{dir}
  310. @end smallexample
  311.  
  312. @item Code Generation Options
  313. @xref{Code Gen Options,,Options for Code Generation Conventions}.
  314. @smallexample
  315. -fcall-saved-@var{reg}  -fcall-used-@var{reg} 
  316. -ffixed-@var{reg}  -finhibit-size-directive 
  317. -fno-common  -fno-ident  -fno-gnu-linker
  318. -fpcc-struct-return  -fpic  -fPIC 
  319. -freg-struct-return  -fshared-data  -fshort-enums
  320. -fshort-double  -fvolatile  -fvolatile-global
  321. -fverbose-asm  +e0  +e1
  322. @end smallexample
  323. @end table
  324.  
  325. @menu
  326. * Overall Options::     Controlling the kind of output:
  327.                         an executable, object files, assembler files,
  328.                         or preprocessed source.
  329. * C Dialect Options::   Controlling the variant of C language compiled.
  330. * C++ Dialect Options:: Variations on C++.
  331. * Warning Options::     How picky should the compiler be?
  332. * Debugging Options::   Symbol tables, measurements, and debugging dumps.
  333. * Optimize Options::    How much optimization?
  334. * Preprocessor Options:: Controlling header files and macro definitions.
  335.                          Also, getting dependency information for Make.
  336. * Assembler Options::   Passing options to the assembler.
  337. * Link Options::        Specifying libraries and so on.
  338. * Directory Options::   Where to find header files and libraries.
  339.                         Where to find the compiler executable files.
  340. * Target Options::      Running a cross-compiler, or an old version of GNU CC.
  341. @end menu
  342.  
  343. @node Overall Options
  344. @section Options Controlling the Kind of Output
  345.  
  346. Compilation can involve up to four stages: preprocessing, compilation
  347. proper, assembly and linking, always in that order.  The first three
  348. stages apply to an individual source file, and end by producing an
  349. object file; linking combines all the object files (those newly
  350. compiled, and those specified as input) into an executable file.
  351.  
  352. @cindex file name suffix
  353. For any given input file, the file name suffix determines what kind of
  354. compilation is done:
  355.  
  356. @table @code
  357. @item @var{file}.c
  358. C source code which must be preprocessed.
  359.  
  360. @item @var{file}.i
  361. C source code which should not be preprocessed.
  362.  
  363. @item @var{file}.ii
  364. C++ source code which should not be preprocessed.
  365.  
  366. @item @var{file}.m
  367. Objective-C source code.  Note that you must link with the library
  368. @file{libobjc.a} to make an Objective-C program work.
  369.  
  370. @item @var{file}.h
  371. C header file (not to be compiled or linked).
  372.  
  373. @item @var{file}.cc
  374. @itemx @var{file}.cxx
  375. @itemx @var{file}.cpp
  376. @itemx @var{file}.C
  377. C++ source code which must be preprocessed.  Note that in @samp{.cxx},
  378. the last two letters must both be literally @samp{x}.  Likewise,
  379. @samp{.C} refers to a literal capital C.
  380.  
  381. @item @var{file}.s 
  382. Assembler code.
  383.  
  384. @item @var{file}.S
  385. Assembler code which must be preprocessed.
  386.  
  387. @item @var{other}
  388. An object file to be fed straight into linking.
  389. Any file name with no recognized suffix is treated this way.
  390. @end table
  391.  
  392. You can specify the input language explicitly with the @samp{-x} option:
  393.  
  394. @table @code
  395. @item -x @var{language}
  396. Specify explicitly the @var{language} for the following input files
  397. (rather than letting the compiler choose a default based on the file
  398. name suffix).  This option applies to all following input files until
  399. the next @samp{-x} option.  Possible values for @var{language} are:
  400. @example
  401. c  objective-c  c++
  402. c-header  cpp-output  c++-cpp-output
  403. assembler  assembler-with-cpp
  404. @end example
  405.  
  406. @item -x none
  407. Turn off any specification of a language, so that subsequent files are
  408. handled according to their file name suffixes (as they are if @samp{-x}
  409. has not been used at all).
  410. @end table
  411.  
  412. If you only want some of the stages of compilation, you can use
  413. @samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and
  414. one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where
  415. @code{gcc} is to stop.  Note that some combinations (for example,
  416. @samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all.
  417.  
  418. @table @code
  419. @item -c
  420. Compile or assemble the source files, but do not link.  The linking
  421. stage simply is not done.  The ultimate output is in the form of an
  422. object file for each source file.
  423.  
  424. By default, the object file name for a source file is made by replacing
  425. the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
  426.  
  427. Unrecognized input files, not requiring compilation or assembly, are
  428. ignored.
  429.  
  430. @item -S
  431. Stop after the stage of compilation proper; do not assemble.  The output
  432. is in the form of an assembler code file for each non-assembler input
  433. file specified.
  434.  
  435. By default, the assembler file name for a source file is made by
  436. replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
  437.  
  438. Input files that don't require compilation are ignored.
  439.  
  440. @item -E
  441. Stop after the preprocessing stage; do not run the compiler proper.  The
  442. output is in the form of preprocessed source code, which is sent to the
  443. standard output.
  444.  
  445. Input files which don't require preprocessing are ignored.
  446.  
  447. @cindex output file option
  448. @item -o @var{file}
  449. Place output in file @var{file}.  This applies regardless to whatever
  450. sort of output is being produced, whether it be an executable file,
  451. an object file, an assembler file or preprocessed C code.
  452.  
  453. Since only one output file can be specified, it does not make sense to
  454. use @samp{-o} when compiling more than one input file, unless you are
  455. producing an executable file as output.
  456.  
  457. If @samp{-o} is not specified, the default is to put an executable file
  458. in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
  459. @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
  460. all preprocessed C source on standard output.@refill
  461.  
  462. @item -v
  463. Print (on standard error output) the commands executed to run the stages
  464. of compilation.  Also print the version number of the compiler driver
  465. program and of the preprocessor and the compiler proper.
  466.  
  467. @item -pipe
  468. Use pipes rather than temporary files for communication between the
  469. various stages of compilation.  This fails to work on some systems where
  470. the assembler is unable to read from a pipe; but the GNU assembler has
  471. no trouble.
  472. @end table
  473.  
  474. @node Invoking G++
  475. @section Compiling C++ Programs
  476.  
  477. @cindex suffixes for C++ source
  478. @cindex C++ source file suffixes
  479. C++ source files conventionally use one of the suffixes @samp{.C},
  480. @samp{.cc}, @samp{cpp}, or @samp{.cxx}; preprocessed C++ files use the
  481. suffix @samp{.ii}.  GNU CC recognizes files with these names and
  482. compiles them as C++ programs even if you call the compiler the same way
  483. as for compiling C programs (usually with the name @code{gcc}).
  484.  
  485. @findex g++
  486. @findex c++
  487. However, C++ programs often require class libraries as well as a
  488. compiler that understands the C++ language---and under some
  489. circumstances, you might want to compile programs from standard input,
  490. or otherwise without a suffix that flags them as C++ programs.
  491. @code{g++} is a program that calls GNU CC with the default language
  492. set to C++, and automatically specifies linking against the GNU class
  493. library libg++.
  494. @cindex @code{g++ 1.@var{xx}}
  495. @cindex @code{g++}, separate compiler
  496. @cindex @code{g++} older version
  497. @footnote{Prior to release 2 of the compiler,
  498. there was a separate @code{g++} compiler.  That version was based on GNU
  499. CC, but not integrated with it.  Versions of @code{g++} with a
  500. @samp{1.@var{xx}} version number---for example, @code{g++} version 1.37
  501. or 1.42---are much less reliable than the versions integrated with GCC
  502. 2.  Moreover, combining G++ @samp{1.@var{xx}} with a version 2 GCC will
  503. simply not work.} On many systems, the script @code{g++} is also
  504. installed with the name @code{c++}.
  505.  
  506. @cindex invoking @code{g++}
  507. When you compile C++ programs, you may specify many of the same
  508. command-line options that you use for compiling programs in any
  509. language; or command-line options meaningful for C and related
  510. languages; or options that are meaningful only for C++ programs.
  511. @xref{C Dialect Options,,Options Controlling C Dialect}, for
  512. explanations of options for languages related to C.
  513. @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
  514. explanations of options that are meaningful only for C++ programs.
  515.  
  516. @node C Dialect Options
  517. @section Options Controlling C Dialect
  518. @cindex dialect options
  519. @cindex language dialect options
  520. @cindex options, dialect
  521.  
  522. The following options control the dialect of C (or languages derived
  523. from C, such as C++ and Objective C) that the compiler accepts:
  524.  
  525. @table @code
  526. @cindex ANSI support
  527. @item -ansi
  528. Support all ANSI standard C programs.
  529.  
  530. This turns off certain features of GNU C that are incompatible with ANSI
  531. C, such as the @code{asm}, @code{inline} and @code{typeof} keywords, and
  532. predefined macros such as @code{unix} and @code{vax} that identify the
  533. type of system you are using.  It also enables the undesirable and
  534. rarely used ANSI trigraph feature, and disallows @samp{$} as part of
  535. identifiers.
  536.  
  537. The alternate keywords @code{__asm__}, @code{__extension__},
  538. @code{__inline__} and @code{__typeof__} continue to work despite
  539. @samp{-ansi}.  You would not want to use them in an ANSI C program, of
  540. course, but it is useful to put them in header files that might be included
  541. in compilations done with @samp{-ansi}.  Alternate predefined macros
  542. such as @code{__unix__} and @code{__vax__} are also available, with or
  543. without @samp{-ansi}.
  544.  
  545. The @samp{-ansi} option does not cause non-ANSI programs to be
  546. rejected gratuitously.  For that, @samp{-pedantic} is required in
  547. addition to @samp{-ansi}.  @xref{Warning Options}.
  548.  
  549. The macro @code{__STRICT_ANSI__} is predefined when the @samp{-ansi}
  550. option is used.  Some header files may notice this macro and refrain
  551. from declaring certain functions or defining certain macros that the
  552. ANSI standard doesn't call for; this is to avoid interfering with any
  553. programs that might use these names for other things.
  554.  
  555. The functions @code{alloca}, @code{abort}, @code{exit}, and
  556. @code{_exit} are not builtin functions when @samp{-ansi} is used.
  557.  
  558. @item -fno-asm
  559. Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
  560. keyword.  These words may then be used as identifiers.  You can use the
  561. keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
  562. instead.  @samp{-ansi} implies @samp{-fno-asm}.
  563.  
  564. @item -fno-builtin
  565. @cindex builtin functions
  566. @findex abort
  567. @findex abs
  568. @findex alloca
  569. @findex cos
  570. @findex exit
  571. @findex fabs
  572. @findex ffs
  573. @findex labs
  574. @findex memcmp
  575. @findex memcpy
  576. @findex sin
  577. @findex sqrt
  578. @findex strcmp
  579. @findex strcpy
  580. @findex strlen
  581. Don't recognize builtin functions that do not begin with two leading
  582. underscores.  Currently, the functions affected include @code{abort},
  583. @code{abs}, @code{alloca}, @code{cos}, @code{exit}, @code{fabs},
  584. @code{ffs}, @code{labs}, @code{memcmp}, @code{memcpy}, @code{sin},
  585. @code{sqrt}, @code{strcmp}, @code{strcpy}, and @code{strlen}.
  586.  
  587. GCC normally generates special code to handle certain builtin functions
  588. more efficiently; for instance, calls to @code{alloca} may become single
  589. instructions that adjust the stack directly, and calls to @code{memcpy}
  590. may become inline copy loops.  The resulting code is often both smaller
  591. and faster, but since the function calls no longer appear as such, you
  592. cannot set a breakpoint on those calls, nor can you change the behavior
  593. of the functions by linking with a different library.
  594.  
  595. The @samp{-ansi} option prevents @code{alloca} and @code{ffs} from being
  596. builtin functions, since these functions do not have an ANSI standard
  597. meaning.
  598.  
  599. @item -trigraphs
  600. Support ANSI C trigraphs.  You don't want to know about this
  601. brain-damage.  The @samp{-ansi} option implies @samp{-trigraphs}.
  602.  
  603. @cindex traditional C language
  604. @cindex C language, traditional
  605. @item -traditional
  606. Attempt to support some aspects of traditional C compilers.
  607. Specifically:
  608.  
  609. @itemize @bullet
  610. @item
  611. All @code{extern} declarations take effect globally even if they
  612. are written inside of a function definition.  This includes implicit
  613. declarations of functions.
  614.  
  615. @item
  616. The newer keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
  617. and @code{volatile} are not recognized.  (You can still use the
  618. alternative keywords such as @code{__typeof__}, @code{__inline__}, and
  619. so on.)
  620.  
  621. @item
  622. Comparisons between pointers and integers are always allowed.
  623.  
  624. @item
  625. Integer types @code{unsigned short} and @code{unsigned char} promote
  626. to @code{unsigned int}.
  627.  
  628. @item
  629. Out-of-range floating point literals are not an error.
  630.  
  631. @item
  632. Certain constructs which ANSI regards as a single invalid preprocessing
  633. number, such as @samp{0xe-0xd}, are treated as expressions instead.
  634.  
  635. @item
  636. String ``constants'' are not necessarily constant; they are stored in
  637. writable space, and identical looking constants are allocated
  638. separately.  (This is the same as the effect of
  639. @samp{-fwritable-strings}.)
  640.  
  641. @cindex @code{longjmp} and automatic variables
  642. @item
  643. All automatic variables not declared @code{register} are preserved by
  644. @code{longjmp}.  Ordinarily, GNU C follows ANSI C: automatic variables
  645. not declared @code{volatile} may be clobbered.
  646.  
  647. @item
  648. @kindex \x
  649. @kindex \a
  650. @cindex escape sequences, traditional
  651. The character escape sequences @samp{\x} and @samp{\a} evaluate as the
  652. literal characters @samp{x} and @samp{a} respectively.  Without
  653. @w{@samp{-traditional}}, @samp{\x} is a prefix for the hexadecimal
  654. representation of a character, and @samp{\a} produces a bell.
  655.  
  656. @item
  657. In C++ programs, assignment to @code{this} is permitted with
  658. @samp{-traditional}.  (The option @samp{-fthis-is-variable} also has
  659. this effect.)
  660. @end itemize
  661.  
  662. You may wish to use @samp{-fno-builtin} as well as @samp{-traditional}
  663. if your program uses names that are normally GNU C builtin functions for
  664. other purposes of its own.
  665.  
  666. You cannot use @samp{-traditional} if you include any header files that
  667. rely on ANSI C features.  Some vendors are starting to ship systems with
  668. ANSI C header files and you cannot use @samp{-traditional} on such
  669. systems to compile files that include any system headers.
  670.  
  671. @item
  672. In the preprocessor, comments convert to nothing at all, rather than
  673. to a space.  This allows traditional token concatenation.
  674.  
  675. @item
  676. In preprocessor directive, the @samp{#} symbol must appear as the first
  677. character of a line.
  678.  
  679. @item
  680. In the preprocessor, macro arguments are recognized within string
  681. constants in a macro definition (and their values are stringified,
  682. though without additional quote marks, when they appear in such a
  683. context).  The preprocessor always considers a string constant to end
  684. at a newline.
  685.  
  686. @item
  687. @cindex detecting @w{@samp{-traditional}}
  688. The predefined macro @code{__STDC__} is not defined when you use
  689. @samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
  690. which @code{__GNUC__} indicates are not affected by
  691. @samp{-traditional}).  If you need to write header files that work
  692. differently depending on whether @samp{-traditional} is in use, by
  693. testing both of these predefined macros you can distinguish four
  694. situations: GNU C, traditional GNU C, other ANSI C compilers, and other
  695. old C compilers.  @xref{Standard Predefined,,Standard Predefined
  696. Macros,cpp.info,The C Preprocessor}, for more discussion of these and other
  697. predefined macros.
  698.  
  699. @item
  700. @cindex string constants vs newline
  701. @cindex newline vs string constants
  702. The preprocessor considers a string constant to end at a newline (unless
  703. the newline is escaped with @samp{\}).  (Without @w{@samp{-traditional}},
  704. string constants can contain the newline character as typed.)
  705.  
  706. @item -traditional-cpp
  707. Attempt to support some aspects of traditional C preprocessors.
  708. This includes the last five items in the table immediately above,
  709. but none of the other effects of @samp{-traditional}.
  710.  
  711. @item -fcond-mismatch
  712. Allow conditional expressions with mismatched types in the second and
  713. third arguments.  The value of such an expression is void.
  714.  
  715. @item -funsigned-char
  716. Let the type @code{char} be unsigned, like @code{unsigned char}.
  717.  
  718. Each kind of machine has a default for what @code{char} should
  719. be.  It is either like @code{unsigned char} by default or like
  720. @code{signed char} by default.
  721.  
  722. Ideally, a portable program should always use @code{signed char} or
  723. @code{unsigned char} when it depends on the signedness of an object.
  724. But many programs have been written to use plain @code{char} and
  725. expect it to be signed, or expect it to be unsigned, depending on the
  726. machines they were written for.  This option, and its inverse, let you
  727. make such a program work with the opposite default.
  728.  
  729. The type @code{char} is always a distinct type from each of
  730. @code{signed char} or @code{unsigned char}, even though its behavior
  731. is always just like one of those two.
  732.  
  733. @item -fsigned-char
  734. Let the type @code{char} be signed, like @code{signed char}.
  735.  
  736. Note that this is equivalent to @samp{-fno-unsigned-char}, which is
  737. the negative form of @samp{-funsigned-char}.  Likewise, the option
  738. @samp{-fno-signed-char} is equivalent to @samp{-funsigned-char}.
  739.  
  740. @item -fsigned-bitfields
  741. @itemx -funsigned-bitfields
  742. @itemx -fno-signed-bitfields
  743. @itemx -fno-unsigned-bitfields
  744. These options control whether a bitfield is signed or unsigned, when the
  745. declaration does not use either @code{signed} or @code{unsigned}.  By
  746. default, such a bitfield is signed, because this is consistent: the
  747. basic integer types such as @code{int} are signed types.
  748.  
  749. However, when @samp{-traditional} is used, bitfields are all unsigned
  750. no matter what.
  751.  
  752. @item -fwritable-strings
  753. Store string constants in the writable data segment and don't uniquize
  754. them.  This is for compatibility with old programs which assume they can
  755. write into string constants.  The option @samp{-traditional} also has
  756. this effect.
  757.  
  758. Writing into string constants is a very bad idea; ``constants'' should
  759. be constant.
  760.  
  761. @item -fallow-single-precision
  762. Do not promote single precision math operations to double precision,
  763. even when compiling with @samp{-traditional}.
  764.  
  765. Traditional K&R C promotes all floating point operations to double
  766. precision, regardless of the sizes of the operands.   On the
  767. architecture for which you are compiling, single precision may be faster
  768. than double precision.   If you must use @samp{-traditional}, but want
  769. to use single precision operations when the operands are single
  770. precision, use this option.   This option has no effect when compiling
  771. with ANSI or GNU C conventions (the default).
  772.  
  773. @end table
  774.  
  775. @node C++ Dialect Options
  776. @section Options Controlling C++ Dialect
  777.  
  778. @cindex compiler options, C++
  779. @cindex C++ options, command line
  780. @cindex options, C++
  781. This section describes the command-line options that are only meaningful
  782. for C++ programs; but you can also use most of the GNU compiler options
  783. regardless of what language your program is in.  For example, you
  784. might compile a file @code{firstClass.C} like this:
  785.  
  786. @example
  787. g++ -g -felide-constructors -O -c firstClass.C
  788. @end example
  789.  
  790. @noindent
  791. In this example, only @samp{-felide-constructors} is an option meant
  792. only for C++ programs; you can use the other options with any
  793. language supported by GNU CC.
  794.  
  795. Here is a list of options that are @emph{only} for compiling C++ programs:
  796.  
  797. @table @code
  798. @item -fno-access-control
  799. Turn off all access checking.  This switch is mainly useful for working
  800. around bugs in the access control code.
  801.  
  802. @item -fall-virtual
  803. Treat all possible member functions as virtual, implicitly.
  804. All member functions (except for constructor functions and @code{new} or
  805. @code{delete} member operators) are treated as virtual functions of the
  806. class where they appear.
  807.  
  808. This does not mean that all calls to these member functions will be made
  809. through the internal table of virtual functions.  Under some
  810. circumstances, the compiler can determine that a call to a given virtual
  811. function can be made directly; in these cases the calls are direct in
  812. any case.
  813.  
  814. @item -fconserve-space
  815. Put uninitialized or runtime-initialized global variables into the
  816. common segment, as C does.  This saves space in the executable at the
  817. cost of not diagnosing duplicate definitions.  If your program
  818. mysteriously crashes after @code{main()} has completed, you may have an
  819. object that is being destroyed twice because two definitions were merged.
  820.  
  821. @item -fdollars-in-identifiers
  822. Accept @samp{$} in identifiers.  You can also explicitly prohibit use of
  823. @samp{$} with the option @samp{-fno-dollars-in-identifiers}.  (GNU C++
  824. allows @samp{$} by default on some target systems but not others.)
  825. Traditional C allowed the character @samp{$} to form part of
  826. identifiers.  However, ANSI C and C++ forbid @samp{$} in identifiers.
  827.  
  828. @item -fenum-int-equiv
  829. Permit implicit conversion of @code{int} to enumeration types.  Normally
  830. GNU C++ allows conversion of @code{enum} to @code{int}, but not the
  831. other way around.
  832.  
  833. @item -fexternal-templates
  834. Cause template instantiations to obey @samp{#pragma interface} and
  835. @samp{implementation}; template instances are emitted or not according
  836. to the location of the template definition.  @xref{Template
  837. Instantiation}, for more information.
  838.  
  839. @item -falt-external-templates
  840. Similar to -fexternal-templates, but template instances are emitted or
  841. not according to the place where they are first instantiated.
  842. @xref{Template Instantiation}, for more information.
  843.  
  844. @item -fno-implicit-templates
  845. Never emit code for templates which are instantiated implicitly (i.e. by
  846. use); only emit code for explicit instantiations.  @xref{Template
  847. Instantiation}, for more information.
  848.  
  849. @item -fhandle-signatures
  850. Recognize the @code{signature} and @code{sigof} keywords for specifying
  851. abstract types.  The default (@samp{-fno-handle-signatures}) is not to
  852. recognize them.  @xref{C++ Signatures, Type Abstraction using
  853. Signatures}.
  854.  
  855. @item -fhuge-objects
  856. Support virtual function calls for objects that exceed the size
  857. representable by a @samp{short int}.  Users should not use this flag by
  858. default; if you need to use it, the compiler will tell you so.  If you
  859. compile any of your code with this flag, you must compile @emph{all} of
  860. your code with this flag (including libg++, if you use it).
  861.  
  862. This flag is not useful when compiling with -fvtable-thunks.
  863.  
  864. @item -fno-implement-inlines
  865. To save space, do not emit out-of-line copies of inline functions
  866. controlled by @samp{#pragma implementation}.  This will cause linker
  867. errors if these functions are not inlined everywhere they are called.
  868.  
  869. @item -fmemoize-lookups
  870. @itemx -fsave-memoized
  871. Use heuristics to compile faster.  These heuristics are not enabled by
  872. default, since they are only effective for certain input files.  Other
  873. input files compile more slowly.
  874.  
  875. The first time the compiler must build a call to a member function (or
  876. reference to a data member), it must (1) determine whether the class
  877. implements member functions of that name; (2) resolve which member
  878. function to call (which involves figuring out what sorts of type
  879. conversions need to be made); and (3) check the visibility of the member
  880. function to the caller.  All of this adds up to slower compilation.
  881. Normally, the second time a call is made to that member function (or
  882. reference to that data member), it must go through the same lengthy
  883. process again.  This means that code like this:
  884.  
  885. @smallexample
  886. cout << "This " << p << " has " << n << " legs.\n";
  887. @end smallexample
  888.  
  889. @noindent
  890. makes six passes through all three steps.  By using a software cache, a
  891. ``hit'' significantly reduces this cost.  Unfortunately, using the cache
  892. introduces another layer of mechanisms which must be implemented, and so
  893. incurs its own overhead.  @samp{-fmemoize-lookups} enables the software
  894. cache.
  895.  
  896. Because access privileges (visibility) to members and member functions
  897. may differ from one function context to the next, G++ may need to flush
  898. the cache.  With the @samp{-fmemoize-lookups} flag, the cache is flushed
  899. after every function that is compiled.  The @samp{-fsave-memoized} flag
  900. enables the same software cache, but when the compiler determines that
  901. the context of the last function compiled would yield the same access
  902. privileges of the next function to compile, it preserves the cache.
  903. This is most helpful when defining many member functions for the same
  904. class: with the exception of member functions which are friends of other
  905. classes, each member function has exactly the same access privileges as
  906. every other, and the cache need not be flushed.
  907.  
  908. @item -fno-strict-prototype
  909. Treat a function declaration with no arguments, such as @samp{int foo
  910. ();}, as C would treat it---as saying nothing about the number of
  911. arguments or their types.  Normally, such a declaration in C++ means
  912. that the function @code{foo} takes no arguments.
  913.  
  914. This option does not work with operator overloading, which places
  915. constraints on the parameter types.
  916.  
  917. @item -fnonnull-objects
  918. Assume that objects reached through references are not null.
  919.  
  920. Normally, GNU C++ makes conservative assumptions about objects reached
  921. through references.  For example, the compiler must check that @code{a}
  922. is not null in code like the following:
  923.  
  924. @example
  925. obj &a = g ();
  926. a.f (2);
  927. @end example
  928.  
  929. Checking that references of this sort have non-null values requires
  930. extra code, however, and it is unnecessary for many programs.  You can
  931. use @w{@samp{-fnonnull-objects}} to omit the checks for null, if your
  932. program doesn't require checking.
  933.  
  934. This checking is currently only done for conversions to virtual base classes.
  935.  
  936. @item -fthis-is-variable
  937. Permit assignment to @code{this}.  The incorporation of user-defined
  938. free store management into C++ has made assignment to @samp{this} an
  939. anachronism.  Therefore, by default it is invalid to assign to
  940. @code{this} within a class member function; that is, GNU C++ treats
  941. @samp{this} in a member function of class @code{X} as a non-lvalue of
  942. type @samp{X *}.  However, for backwards compatibility, you can make it
  943. valid with @samp{-fthis-is-variable}.
  944.  
  945. @item -fvtable-thunks
  946. Use @samp{thunks} to implement the virtual function dispatch table
  947. (@samp{vtable}).  The traditional (cfront-style) approach to
  948. implementing vtables was to store a pointer to the function and two
  949. offsets for adjusting the @samp{this} pointer at the call site.  Newer
  950. implementations store a single pointer to a @samp{thunk} function which
  951. does any necessary adjustment and then calls the target function.
  952.  
  953. This option also enables a heuristic for controlling emission of
  954. vtables; if a class has any non-inline virtual functions, the vtable
  955. will be emitted in the translation unit containing the first one of
  956. those.
  957.  
  958. @item -nostdinc++
  959. Do not search for header files in the standard directories specific to
  960. C++, but do still search the other standard directories.  (This option
  961. is used when building libg++.)
  962.  
  963. @item -traditional
  964. For C++ programs (in addition to the effects that apply to both C and
  965. C++), this has the same effect as @samp{-fthis-is-variable}.
  966. @xref{C Dialect Options,, Options Controlling C Dialect}.
  967. @end table
  968.  
  969. In addition, these optimization, warning, and code generation options
  970. have meanings only for C++ programs:
  971.  
  972. @table @code
  973. @item -fno-default-inline
  974. Do not assume @samp{inline} for functions defined inside a class scope.
  975. @xref{Optimize Options,,Options That Control Optimization}.
  976.  
  977. @item -Wenum-clash
  978. @itemx -Woverloaded-virtual
  979. @itemx -Wtemplate-debugging
  980. Warnings that apply only to C++ programs.  @xref{Warning
  981. Options,,Options to Request or Suppress Warnings}.
  982.  
  983. @item +e@var{n}
  984. Control how virtual function definitions are used, in a fashion
  985. compatible with @code{cfront} 1.x.  @xref{Code Gen Options,,Options for
  986. Code Generation Conventions}.
  987. @end table
  988.  
  989. @node Warning Options
  990. @section Options to Request or Suppress Warnings
  991. @cindex options to control warnings
  992. @cindex warning messages
  993. @cindex messages, warning
  994. @cindex suppressing warnings
  995.  
  996. Warnings are diagnostic messages that report constructions which
  997. are not inherently erroneous but which are risky or suggest there
  998. may have been an error.
  999.  
  1000. You can request many specific warnings with options beginning @samp{-W},
  1001. for example @samp{-Wimplicit} to request warnings on implicit
  1002. declarations.  Each of these specific warning options also has a
  1003. negative form beginning @samp{-Wno-} to turn off warnings;
  1004. for example, @samp{-Wno-implicit}.  This manual lists only one of the
  1005. two forms, whichever is not the default.
  1006.  
  1007. These options control the amount and kinds of warnings produced by GNU
  1008. CC:
  1009.  
  1010. @table @code
  1011. @cindex syntax checking
  1012. @item -fsyntax-only
  1013. Check the code for syntax errors, but don't do anything beyond that.
  1014.  
  1015. @item -w
  1016. Inhibit all warning messages.
  1017.  
  1018. @item -Wno-import
  1019. Inhibit warning messages about the use of @samp{#import}.
  1020.  
  1021. @item -pedantic
  1022. Issue all the warnings demanded by strict ANSI standard C; reject
  1023. all programs that use forbidden extensions.  
  1024.  
  1025. Valid ANSI standard C programs should compile properly with or without
  1026. this option (though a rare few will require @samp{-ansi}).  However,
  1027. without this option, certain GNU extensions and traditional C features
  1028. are supported as well.  With this option, they are rejected.
  1029.  
  1030. @samp{-pedantic} does not cause warning messages for use of the
  1031. alternate keywords whose names begin and end with @samp{__}.  Pedantic
  1032. warnings are also disabled in the expression that follows
  1033. @code{__extension__}.  However, only system header files should use
  1034. these escape routes; application programs should avoid them.
  1035. @xref{Alternate Keywords}.
  1036.  
  1037. This option is not intended to be @i{useful}; it exists only to satisfy
  1038. pedants who would otherwise claim that GNU CC fails to support the ANSI
  1039. standard.
  1040.  
  1041. Some users try to use @samp{-pedantic} to check programs for strict ANSI
  1042. C conformance.  They soon find that it does not do quite what they want:
  1043. it finds some non-ANSI practices, but not all---only those for which
  1044. ANSI C @emph{requires} a diagnostic.
  1045.  
  1046. A feature to report any failure to conform to ANSI C might be useful in
  1047. some instances, but would require considerable additional work and would
  1048. be quite different from @samp{-pedantic}.  We recommend, rather, that
  1049. users take advantage of the extensions of GNU C and disregard the
  1050. limitations of other compilers.  Aside from certain supercomputers and
  1051. obsolete small machines, there is less and less reason ever to use any
  1052. other C compiler other than for bootstrapping GNU CC.
  1053.  
  1054. @item -pedantic-errors
  1055. Like @samp{-pedantic}, except that errors are produced rather than
  1056. warnings.
  1057.  
  1058. @item -W
  1059. Print extra warning messages for these events:
  1060.  
  1061. @itemize @bullet
  1062. @cindex @code{longjmp} warnings
  1063. @item
  1064. A nonvolatile automatic variable might be changed by a call to
  1065. @code{longjmp}.  These warnings as well are possible only in
  1066. optimizing compilation.
  1067.  
  1068. The compiler sees only the calls to @code{setjmp}.  It cannot know
  1069. where @code{longjmp} will be called; in fact, a signal handler could
  1070. call it at any point in the code.  As a result, you may get a warning
  1071. even when there is in fact no problem because @code{longjmp} cannot
  1072. in fact be called at the place which would cause a problem.
  1073.  
  1074. @item
  1075. A function can return either with or without a value.  (Falling
  1076. off the end of the function body is considered returning without
  1077. a value.)  For example, this function would evoke such a
  1078. warning:
  1079.  
  1080. @smallexample
  1081. @group
  1082. foo (a)
  1083. @{
  1084.   if (a > 0)
  1085.     return a;
  1086. @}
  1087. @end group
  1088. @end smallexample
  1089.  
  1090. @item
  1091. An expression-statement contains no side effects.
  1092.  
  1093. @item
  1094. An unsigned value is compared against zero with @samp{<} or @samp{<=}.
  1095.  
  1096. @item
  1097. A comparison like @samp{x<=y<=z} appears; this is equivalent to
  1098. @samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from
  1099. that of ordinary mathematical notation.
  1100.  
  1101. @item
  1102. Storage-class specifiers like @code{static} are not the first things in
  1103. a declaration.  According to the C Standard, this usage is obsolescent.
  1104.  
  1105. @item
  1106. An aggregate has a partly bracketed initializer.
  1107. For example, the following code would evoke such a warning,
  1108. because braces are missing around the initializer for @code{x.h}:
  1109.  
  1110. @smallexample
  1111. struct s @{ int f, g; @};
  1112. struct t @{ struct s h; int i; @};
  1113. struct t x = @{ 1, 2, 3 @};
  1114. @end smallexample
  1115. @end itemize
  1116.  
  1117. @item -Wimplicit
  1118. Warn whenever a function or parameter is implicitly declared.
  1119.  
  1120. @item -Wreturn-type
  1121. Warn whenever a function is defined with a return-type that defaults
  1122. to @code{int}.  Also warn about any @code{return} statement with no
  1123. return-value in a function whose return-type is not @code{void}.
  1124.  
  1125. @item -Wunused
  1126. Warn whenever a variable is unused aside from its declaration,
  1127. whenever a function is declared static but never defined, whenever a
  1128. label is declared but not used, and whenever a statement computes a
  1129. result that is explicitly not used.
  1130.  
  1131. To suppress this warning for a local variable or expression, simply cast
  1132. it to void.  This will also work for file-scope variables, but if you
  1133. want to mark them used at the point of definition, you can use this
  1134. macro:
  1135.  
  1136. @smallexample
  1137. #define USE(var) \
  1138.   static void *const use_##var = (&use_##var, &var, 0)
  1139.  
  1140. USE (string);
  1141. @end smallexample
  1142.  
  1143. @item -Wswitch
  1144. Warn whenever a @code{switch} statement has an index of enumeral type
  1145. and lacks a @code{case} for one or more of the named codes of that
  1146. enumeration.  (The presence of a @code{default} label prevents this
  1147. warning.)  @code{case} labels outside the enumeration range also
  1148. provoke warnings when this option is used.
  1149.  
  1150. @item -Wcomment
  1151. Warn whenever a comment-start sequence @samp{/*} appears in a comment.
  1152.  
  1153. @item -Wtrigraphs
  1154. Warn if any trigraphs are encountered (assuming they are enabled).
  1155.  
  1156. @item -Wformat
  1157. Check calls to @code{printf} and @code{scanf}, etc., to make sure that
  1158. the arguments supplied have types appropriate to the format string
  1159. specified.
  1160.  
  1161. @item -Wchar-subscripts
  1162. Warn if an array subscript has type @code{char}.  This is a common cause
  1163. of error, as programmers often forget that this type is signed on some
  1164. machines.
  1165.  
  1166. @item -Wuninitialized
  1167. An automatic variable is used without first being initialized.
  1168.  
  1169. These warnings are possible only in optimizing compilation,
  1170. because they require data flow information that is computed only
  1171. when optimizing.  If you don't specify @samp{-O}, you simply won't
  1172. get these warnings.
  1173.  
  1174. These warnings occur only for variables that are candidates for
  1175. register allocation.  Therefore, they do not occur for a variable that
  1176. is declared @code{volatile}, or whose address is taken, or whose size
  1177. is other than 1, 2, 4 or 8 bytes.  Also, they do not occur for
  1178. structures, unions or arrays, even when they are in registers.
  1179.  
  1180. Note that there may be no warning about a variable that is used only
  1181. to compute a value that itself is never used, because such
  1182. computations may be deleted by data flow analysis before the warnings
  1183. are printed.
  1184.  
  1185. These warnings are made optional because GNU CC is not smart
  1186. enough to see all the reasons why the code might be correct
  1187. despite appearing to have an error.  Here is one example of how
  1188. this can happen:
  1189.  
  1190. @smallexample
  1191. @{
  1192.   int x;
  1193.   switch (y)
  1194.     @{
  1195.     case 1: x = 1;
  1196.       break;
  1197.     case 2: x = 4;
  1198.       break;
  1199.     case 3: x = 5;
  1200.     @}
  1201.   foo (x);
  1202. @}
  1203. @end smallexample
  1204.  
  1205. @noindent
  1206. If the value of @code{y} is always 1, 2 or 3, then @code{x} is
  1207. always initialized, but GNU CC doesn't know this.  Here is
  1208. another common case:
  1209.  
  1210. @smallexample
  1211. @{
  1212.   int save_y;
  1213.   if (change_y) save_y = y, y = new_y;
  1214.   @dots{}
  1215.   if (change_y) y = save_y;
  1216. @}
  1217. @end smallexample
  1218.  
  1219. @noindent
  1220. This has no bug because @code{save_y} is used only if it is set.
  1221.  
  1222. Some spurious warnings can be avoided if you declare all the functions
  1223. you use that never return as @code{noreturn}.  @xref{Function
  1224. Attributes}.
  1225.  
  1226. @item -Wparentheses
  1227. Warn if parentheses are omitted in certain contexts, such
  1228. as when there is an assignment in a context where a truth value
  1229. is expected, or when operators are nested whose precedence people
  1230. often get confused about.
  1231.  
  1232. @item -Wenum-clash
  1233. @cindex enumeration clash warnings
  1234. @cindex warning for enumeration conversions
  1235. Warn about conversion between different enumeration types.
  1236. (C++ only).
  1237.  
  1238. @item -Wtemplate-debugging
  1239. @cindex template debugging
  1240. When using templates in a C++ program, warn if debugging is not yet
  1241. fully available (C++ only).
  1242.  
  1243. @item -Wreorder (C++ only)
  1244. @cindex reordering, warning
  1245. @cindex warning for reordering of member initializers
  1246. Warn when the order of member initializers given in the code does not
  1247. match the order in which they must be executed.  For instance:
  1248.  
  1249. @smallexample
  1250. struct A @{
  1251.   int i;
  1252.   int j;
  1253.   A(): j (0), i (1) @{ @}
  1254. @};
  1255. @end smallexample
  1256.  
  1257. Here the compiler will warn that the member initializers for @samp{i}
  1258. and @samp{j} will be rearranged to match the declaration order of the
  1259. members.
  1260.  
  1261. @item -Wall
  1262. All of the above @samp{-W} options combined.  These are all the
  1263. options which pertain to usage that we recommend avoiding and that we
  1264. believe is easy to avoid, even in conjunction with macros.
  1265. @end table
  1266.  
  1267. The remaining @samp{-W@dots{}} options are not implied by @samp{-Wall}
  1268. because they warn about constructions that we consider reasonable to
  1269. use, on occasion, in clean programs.
  1270.  
  1271. @table @code
  1272. @item -Wtraditional
  1273. Warn about certain constructs that behave differently in traditional and
  1274. ANSI C.
  1275.  
  1276. @itemize @bullet
  1277. @item
  1278. Macro arguments occurring within string constants in the macro body.
  1279. These would substitute the argument in traditional C, but are part of
  1280. the constant in ANSI C.
  1281.  
  1282. @item
  1283. A function declared external in one block and then used after the end of
  1284. the block.
  1285.  
  1286. @item
  1287. A @code{switch} statement has an operand of type @code{long}.
  1288. @end itemize
  1289.  
  1290. @item -Wshadow
  1291. Warn whenever a local variable shadows another local variable.
  1292.  
  1293. @item -Wid-clash-@var{len}
  1294. Warn whenever two distinct identifiers match in the first @var{len}
  1295. characters.  This may help you prepare a program that will compile
  1296. with certain obsolete, brain-damaged compilers.
  1297.  
  1298. @item -Wlarger-than-@var{len}
  1299. Warn whenever an object of larger than @var{len} bytes is defined.
  1300.  
  1301. @item -Wpointer-arith
  1302. Warn about anything that depends on the ``size of'' a function type or
  1303. of @code{void}.  GNU C assigns these types a size of 1, for
  1304. convenience in calculations with @code{void *} pointers and pointers
  1305. to functions.
  1306.  
  1307. @item -Wbad-function-cast
  1308. Warn whenever a function call is cast to a non-matching type.
  1309. For example, warn if @code{int malloc()} is cast to @code{anything *}.
  1310.  
  1311. @item -Wcast-qual
  1312. Warn whenever a pointer is cast so as to remove a type qualifier from
  1313. the target type.  For example, warn if a @code{const char *} is cast
  1314. to an ordinary @code{char *}.
  1315.  
  1316. @item -Wcast-align
  1317. Warn whenever a pointer is cast such that the required alignment of the
  1318. target is increased.  For example, warn if a @code{char *} is cast to
  1319. an @code{int *} on machines where integers can only be accessed at
  1320. two- or four-byte boundaries.
  1321.  
  1322. @item -Wwrite-strings
  1323. Give string constants the type @code{const char[@var{length}]} so that
  1324. copying the address of one into a non-@code{const} @code{char *}
  1325. pointer will get a warning.  These warnings will help you find at
  1326. compile time code that can try to write into a string constant, but
  1327. only if you have been very careful about using @code{const} in
  1328. declarations and prototypes.  Otherwise, it will just be a nuisance;
  1329. this is why we did not make @samp{-Wall} request these warnings.
  1330.  
  1331. @item -Wconversion
  1332. Warn if a prototype causes a type conversion that is different from what
  1333. would happen to the same argument in the absence of a prototype.  This
  1334. includes conversions of fixed point to floating and vice versa, and
  1335. conversions changing the width or signedness of a fixed point argument
  1336. except when the same as the default promotion.
  1337.  
  1338. Also, warn if a negative integer constant expression is implicitly
  1339. converted to an unsigned type.  For example, warn about the assignment
  1340. @code{x = -1} if @code{x} is unsigned.  But do not warn about explicit
  1341. casts like @code{(unsigned) -1}.
  1342.  
  1343. @item -Waggregate-return
  1344. Warn if any functions that return structures or unions are defined or
  1345. called.  (In languages where you can return an array, this also elicits
  1346. a warning.)
  1347.  
  1348. @item -Wstrict-prototypes
  1349. Warn if a function is declared or defined without specifying the
  1350. argument types.  (An old-style function definition is permitted without
  1351. a warning if preceded by a declaration which specifies the argument
  1352. types.)
  1353.  
  1354. @item -Wmissing-prototypes
  1355. Warn if a global function is defined without a previous prototype
  1356. declaration.  This warning is issued even if the definition itself
  1357. provides a prototype.  The aim is to detect global functions that fail
  1358. to be declared in header files.
  1359.  
  1360. @item -Wmissing-declarations
  1361. Warn if a global function is defined without a previous declaration.
  1362. Do so even if the definition itself provides a prototype.
  1363. Use this option to detect global functions that are not declared in
  1364. header files.
  1365.  
  1366. @item -Wredundant-decls
  1367. Warn if anything is declared more than once in the same scope, even in
  1368. cases where multiple declaration is valid and changes nothing.
  1369.  
  1370. @item -Wnested-externs
  1371. Warn if an @code{extern} declaration is encountered within an function.
  1372.  
  1373. @item -Winline
  1374. Warn if a function can not be inlined, and either it was declared as inline,
  1375. or else the @samp{-finline-functions} option was given.
  1376.  
  1377. @item -Woverloaded-virtual
  1378. @cindex overloaded virtual fn, warning
  1379. @cindex warning for overloaded virtual fn
  1380. Warn when a derived class function declaration may be an error in
  1381. defining a virtual function (C++ only).  In a derived class, the
  1382. definitions of virtual functions must match the type signature of a
  1383. virtual function declared in the base class.  With this option, the
  1384. compiler warns when you define a function with the same name as a
  1385. virtual function, but with a type signature that does not match any
  1386. declarations from the base class.
  1387.  
  1388. @item -Wsynth (C++ only)
  1389. @cindex warning for synthesized methods
  1390. @cindex synthesized methods, warning
  1391. Warn when g++'s synthesis behavior does not match that of cfront.  For
  1392. instance:
  1393.  
  1394. @smallexample
  1395. struct A @{
  1396.   operator int ();
  1397.   A& operator = (int);
  1398. @};
  1399.  
  1400. main ()
  1401. @{
  1402.   A a,b;
  1403.   a = b;
  1404. @}
  1405. @end smallexample
  1406.  
  1407. In this example, g++ will synthesize a default @samp{A& operator =
  1408. (const A&);}, while cfront will use the user-defined @samp{operator =}.
  1409.  
  1410. @item -Werror
  1411. Make all warnings into errors.
  1412. @end table
  1413.  
  1414. @node Debugging Options
  1415. @section Options for Debugging Your Program or GNU CC
  1416. @cindex options, debugging
  1417. @cindex debugging information options
  1418.  
  1419. GNU CC has various special options that are used for debugging
  1420. either your program or GCC:
  1421.  
  1422. @table @code
  1423. @item -g
  1424. Produce debugging information in the operating system's native format
  1425. (stabs, COFF, XCOFF, or DWARF).  GDB can work with this debugging
  1426. information.
  1427.  
  1428. On most systems that use stabs format, @samp{-g} enables use of extra
  1429. debugging information that only GDB can use; this extra information
  1430. makes debugging work better in GDB but will probably make other debuggers
  1431. crash or
  1432. refuse to read the program.  If you want to control for certain whether
  1433. to generate the extra information, use @samp{-gstabs+}, @samp{-gstabs},
  1434. @samp{-gxcoff+}, @samp{-gxcoff}, @samp{-gdwarf+}, or @samp{-gdwarf}
  1435. (see below).
  1436.  
  1437. Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
  1438. @samp{-O}.  The shortcuts taken by optimized code may occasionally
  1439. produce surprising results: some variables you declared may not exist
  1440. at all; flow of control may briefly move where you did not expect it;
  1441. some statements may not be executed because they compute constant
  1442. results or their values were already at hand; some statements may
  1443. execute in different places because they were moved out of loops.
  1444.  
  1445. Nevertheless it proves possible to debug optimized output.  This makes
  1446. it reasonable to use the optimizer for programs that might have bugs.
  1447.  
  1448. The following options are useful when GNU CC is generated with the
  1449. capability for more than one debugging format.
  1450.  
  1451. @item -ggdb
  1452. Produce debugging information in the native format (if that is supported),
  1453. including GDB extensions if at all possible.
  1454.  
  1455. @item -gstabs
  1456. Produce debugging information in stabs format (if that is supported),
  1457. without GDB extensions.  This is the format used by DBX on most BSD
  1458. systems.  On MIPS, Alpha and System V Release 4 systems this option
  1459. produces stabs debugging output which is not understood by DBX or SDB.
  1460. On System V Release 4 systems this option requires the GNU assembler.
  1461.  
  1462. @item -gstabs+
  1463. Produce debugging information in stabs format (if that is supported),
  1464. using GNU extensions understood only by the GNU debugger (GDB).  The
  1465. use of these extensions is likely to make other debuggers crash or
  1466. refuse to read the program.
  1467.  
  1468. @item -gcoff
  1469. Produce debugging information in COFF format (if that is supported).
  1470. This is the format used by SDB on most System V systems prior to
  1471. System V Release 4.
  1472.  
  1473. @item -gxcoff
  1474. Produce debugging information in XCOFF format (if that is supported).
  1475. This is the format used by the DBX debugger on IBM RS/6000 systems.
  1476.  
  1477. @item -gxcoff+
  1478. Produce debugging information in XCOFF format (if that is supported),
  1479. using GNU extensions understood only by the GNU debugger (GDB).  The
  1480. use of these extensions is likely to make other debuggers crash or
  1481. refuse to read the program.
  1482.  
  1483. @item -gdwarf
  1484. Produce debugging information in DWARF format (if that is supported).
  1485. This is the format used by SDB on most System V Release 4 systems.
  1486.  
  1487. @item -gdwarf+
  1488. Produce debugging information in DWARF format (if that is supported),
  1489. using GNU extensions understood only by the GNU debugger (GDB).  The
  1490. use of these extensions is likely to make other debuggers crash or
  1491. refuse to read the program.
  1492.  
  1493. @item -g@var{level}
  1494. @itemx -ggdb@var{level}
  1495. @itemx -gstabs@var{level}
  1496. @itemx -gcoff@var{level}
  1497. @itemx -gxcoff@var{level}
  1498. @itemx -gdwarf@var{level}
  1499. Request debugging information and also use @var{level} to specify how
  1500. much information.  The default level is 2.
  1501.  
  1502. Level 1 produces minimal information, enough for making backtraces in
  1503. parts of the program that you don't plan to debug.  This includes
  1504. descriptions of functions and external variables, but no information
  1505. about local variables and no line numbers.
  1506.  
  1507. Level 3 includes extra information, such as all the macro definitions
  1508. present in the program.  Some debuggers support macro expansion when
  1509. you use @samp{-g3}.
  1510.  
  1511. @cindex @code{prof}
  1512. @item -p
  1513. Generate extra code to write profile information suitable for the
  1514. analysis program @code{prof}.  You must use this option when compiling
  1515. the source files you want data about, and you must also use it when
  1516. linking.
  1517.  
  1518. @cindex @code{gprof}
  1519. @item -pg
  1520. Generate extra code to write profile information suitable for the
  1521. analysis program @code{gprof}.  You must use this option when compiling
  1522. the source files you want data about, and you must also use it when
  1523. linking.
  1524.  
  1525. @cindex @code{tcov}
  1526. @item -a
  1527. Generate extra code to write profile information for basic blocks, which will
  1528. record the number of times each basic block is executed, the basic block start
  1529. address, and the function name containing the basic block.  If @samp{-g} is
  1530. used, the line number and filename of the start of the basic block will also be
  1531. recorded.  If not overridden by the machine description, the default action is
  1532. to append to the text file @file{bb.out}.
  1533.  
  1534. This data could be analyzed by a program like @code{tcov}.  Note,
  1535. however, that the format of the data is not what @code{tcov} expects.
  1536. Eventually GNU @code{gprof} should be extended to process this data.
  1537.  
  1538. @item -d@var{letters}
  1539. Says to make debugging dumps during compilation at times specified by
  1540. @var{letters}.  This is used for debugging the compiler.  The file names
  1541. for most of the dumps are made by appending a word to the source file
  1542. name (e.g.  @file{foo.c.rtl} or @file{foo.c.jump}).  Here are the
  1543. possible letters for use in @var{letters}, and their meanings:
  1544.  
  1545. @table @samp
  1546. @item M
  1547. Dump all macro definitions, at the end of preprocessing, and write no
  1548. output.
  1549. @item N
  1550. Dump all macro names, at the end of preprocessing.
  1551. @item D
  1552. Dump all macro definitions, at the end of preprocessing, in addition to
  1553. normal output.
  1554. @item y
  1555. Dump debugging information during parsing, to standard error.
  1556. @item r
  1557. Dump after RTL generation, to @file{@var{file}.rtl}.
  1558. @item x
  1559. Just generate RTL for a function instead of compiling it.  Usually used
  1560. with @samp{r}.
  1561. @item j
  1562. Dump after first jump optimization, to @file{@var{file}.jump}.
  1563. @item s
  1564. Dump after CSE (including the jump optimization that sometimes
  1565. follows CSE), to @file{@var{file}.cse}.
  1566. @item L
  1567. Dump after loop optimization, to @file{@var{file}.loop}.
  1568. @item t
  1569. Dump after the second CSE pass (including the jump optimization that
  1570. sometimes follows CSE), to @file{@var{file}.cse2}.
  1571. @item f
  1572. Dump after flow analysis, to @file{@var{file}.flow}.
  1573. @item c
  1574. Dump after instruction combination, to the file
  1575. @file{@var{file}.combine}.
  1576. @item S
  1577. Dump after the first instruction scheduling pass, to
  1578. @file{@var{file}.sched}.
  1579. @item l
  1580. Dump after local register allocation, to
  1581. @file{@var{file}.lreg}.
  1582. @item g
  1583. Dump after global register allocation, to
  1584. @file{@var{file}.greg}.
  1585. @item R
  1586. Dump after the second instruction scheduling pass, to
  1587. @file{@var{file}.sched2}.
  1588. @item J
  1589. Dump after last jump optimization, to @file{@var{file}.jump2}.
  1590. @item d
  1591. Dump after delayed branch scheduling, to @file{@var{file}.dbr}.
  1592. @item k
  1593. Dump after conversion from registers to stack, to @file{@var{file}.stack}.
  1594. @item a
  1595. Produce all the dumps listed above.
  1596. @item m
  1597. Print statistics on memory usage, at the end of the run, to
  1598. standard error.
  1599. @item p
  1600. Annotate the assembler output with a comment indicating which
  1601. pattern and alternative was used.
  1602. @end table
  1603.  
  1604. @item -fpretend-float
  1605. When running a cross-compiler, pretend that the target machine uses the
  1606. same floating point format as the host machine.  This causes incorrect
  1607. output of the actual floating constants, but the actual instruction
  1608. sequence will probably be the same as GNU CC would make when running on
  1609. the target machine.
  1610.  
  1611. @item -save-temps
  1612. Store the usual ``temporary'' intermediate files permanently; place them
  1613. in the current directory and name them based on the source file.  Thus,
  1614. compiling @file{foo.c} with @samp{-c -save-temps} would produce files
  1615. @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.
  1616.  
  1617. @item -print-file-name=@var{library}
  1618. Print the full absolute name of the library file @var{library} that
  1619. would be used when linking---and don't do anything else.  With this
  1620. option, GNU CC does not compile or link anything; it just prints the
  1621. file name.
  1622.  
  1623. @item -print-prog-name=@var{program}
  1624. Like @samp{-print-file-name}, but searches for a program such as @samp{cpp}.
  1625.  
  1626. @item -print-libgcc-file-name
  1627. Same as @samp{-print-file-name=libgcc.a}.
  1628.  
  1629. This is useful when you use @samp{-nostdlib} but you do want to link
  1630. with @file{libgcc.a}.  You can do
  1631.  
  1632. @example
  1633. gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
  1634. @end example
  1635. @end table
  1636.  
  1637. @node Optimize Options
  1638. @section Options That Control Optimization
  1639. @cindex optimize options
  1640. @cindex options, optimization
  1641.  
  1642. These options control various sorts of optimizations:
  1643.  
  1644. @table @code
  1645. @item -O
  1646. @itemx -O1
  1647. Optimize.  Optimizing compilation takes somewhat more time, and a lot
  1648. more memory for a large function.
  1649.  
  1650. Without @samp{-O}, the compiler's goal is to reduce the cost of
  1651. compilation and to make debugging produce the expected results.
  1652. Statements are independent: if you stop the program with a breakpoint
  1653. between statements, you can then assign a new value to any variable or
  1654. change the program counter to any other statement in the function and
  1655. get exactly the results you would expect from the source code.
  1656.  
  1657. Without @samp{-O}, the compiler only allocates variables declared
  1658. @code{register} in registers.  The resulting compiled code is a little
  1659. worse than produced by PCC without @samp{-O}.
  1660.  
  1661. With @samp{-O}, the compiler tries to reduce code size and execution
  1662. time.
  1663.  
  1664. When you specify @samp{-O}, the compiler turns on @samp{-fthread-jumps}
  1665. and @samp{-fdefer-pop} on all machines.  The compiler turns on
  1666. @samp{-fdelayed-branch} on machines that have delay slots, and
  1667. @samp{-fomit-frame-pointer} on machines that can support debugging even
  1668. without a frame pointer.  On some machines the compiler also turns
  1669. on other flags.@refill
  1670.  
  1671. @item -O2
  1672. Optimize even more.  GNU CC performs nearly all supported optimizations
  1673. that do not involve a space-speed tradeoff.  The compiler does not
  1674. perform loop unrolling or function inlining when you specify @samp{-O2}.
  1675. As compared to @samp{-O}, this option increases both compilation time
  1676. and the performance of the generated code.
  1677.  
  1678. @samp{-O2} turns on all optional optimizations except for loop unrolling
  1679. and function inlining.  It also turns on frame pointer elimination on
  1680. machines where doing so does not interfer with debugging.
  1681.  
  1682. @item -O3
  1683. Optimize yet more.  @samp{-O3} turns on all optimizations specified by
  1684. @samp{-O2} and also turns on the @samp{inline-functions} option.
  1685.  
  1686. @item -O0
  1687. Do not optimize.
  1688.  
  1689. If you use multiple @samp{-O} options, with or without level numbers,
  1690. the last such option is the one that is effective.
  1691. @end table
  1692.  
  1693. Options of the form @samp{-f@var{flag}} specify machine-independent
  1694. flags.  Most flags have both positive and negative forms; the negative
  1695. form of @samp{-ffoo} would be @samp{-fno-foo}.  In the table below,
  1696. only one of the forms is listed---the one which is not the default.
  1697. You can figure out the other form by either removing @samp{no-} or
  1698. adding it.
  1699.  
  1700. @table @code
  1701. @item -ffloat-store
  1702. Do not store floating point variables in registers, and inhibit other
  1703. options that might change whether a floating point value is taken from a
  1704. register or memory.
  1705.  
  1706. This option prevents undesirable excess precision on machines such as
  1707. the 68000 where the floating registers (of the 68881) keep more
  1708. precision than a @code{double} is supposed to have.  For most programs,
  1709. the excess precision does only good, but a few programs rely on the
  1710. precise definition of IEEE floating point.  Use @samp{-ffloat-store} for
  1711. such programs.
  1712.  
  1713. @item -fno-default-inline
  1714. Do not make member functions inline by default merely because they are
  1715. defined inside the class scope (C++ only).  Otherwise, when you specify
  1716. @w{@samp{-O}}, member functions defined inside class scope are compiled
  1717. inline by default; i.e., you don't need to add @samp{inline} in front of
  1718. the member function name.
  1719.  
  1720. @item -fno-defer-pop
  1721. Always pop the arguments to each function call as soon as that function
  1722. returns.  For machines which must pop arguments after a function call,
  1723. the compiler normally lets arguments accumulate on the stack for several
  1724. function calls and pops them all at once.
  1725.  
  1726. @item -fforce-mem
  1727. Force memory operands to be copied into registers before doing
  1728. arithmetic on them.  This may produce better code by making all
  1729. memory references potential common subexpressions.  When they are
  1730. not common subexpressions, instruction combination should
  1731. eliminate the separate register-load.  I am interested in hearing
  1732. about the difference this makes.
  1733.  
  1734. @item -fforce-addr
  1735. Force memory address constants to be copied into registers before
  1736. doing arithmetic on them.  This may produce better code just as
  1737. @samp{-fforce-mem} may.  I am interested in hearing about the
  1738. difference this makes.
  1739.  
  1740. @item -fomit-frame-pointer
  1741. Don't keep the frame pointer in a register for functions that
  1742. don't need one.  This avoids the instructions to save, set up and
  1743. restore frame pointers; it also makes an extra register available
  1744. in many functions.  @strong{It also makes debugging impossible on
  1745. some machines.}
  1746.  
  1747. @ifset INTERNALS
  1748. On some machines, such as the Vax, this flag has no effect, because
  1749. the standard calling sequence automatically handles the frame pointer
  1750. and nothing is saved by pretending it doesn't exist.  The
  1751. machine-description macro @code{FRAME_POINTER_REQUIRED} controls
  1752. whether a target machine supports this flag.  @xref{Registers}.@refill
  1753. @end ifset
  1754. @ifclear INTERNALS
  1755. On some machines, such as the Vax, this flag has no effect, because
  1756. the standard calling sequence automatically handles the frame pointer
  1757. and nothing is saved by pretending it doesn't exist.  The
  1758. machine-description macro @code{FRAME_POINTER_REQUIRED} controls
  1759. whether a target machine supports this flag.  @xref{Registers,,Register
  1760. Usage, gcc.info, Using and Porting GCC}.@refill
  1761. @end ifclear
  1762.  
  1763. @item -fno-inline
  1764. Don't pay attention to the @code{inline} keyword.  Normally this option
  1765. is used to keep the compiler from expanding any functions inline.
  1766. Note that if you are not optimizing, no functions can be expanded inline.
  1767.  
  1768. @item -finline-functions
  1769. Integrate all simple functions into their callers.  The compiler
  1770. heuristically decides which functions are simple enough to be worth
  1771. integrating in this way.
  1772.  
  1773. If all calls to a given function are integrated, and the function is
  1774. declared @code{static}, then the function is normally not output as
  1775. assembler code in its own right.
  1776.  
  1777. @item -fkeep-inline-functions
  1778. Even if all calls to a given function are integrated, and the function
  1779. is declared @code{static}, nevertheless output a separate run-time
  1780. callable version of the function.
  1781.  
  1782. @item -fno-function-cse
  1783. Do not put function addresses in registers; make each instruction that
  1784. calls a constant function contain the function's address explicitly.
  1785.  
  1786. This option results in less efficient code, but some strange hacks
  1787. that alter the assembler output may be confused by the optimizations
  1788. performed when this option is not used.
  1789.  
  1790. @item -ffast-math
  1791. This option allows GCC to violate some ANSI or IEEE rules and/or
  1792. specifications in the interest of optimizing code for speed.  For
  1793. example, it allows the compiler to assume arguments to the @code{sqrt}
  1794. function are non-negative numbers and that no floating-point values
  1795. are NaNs.
  1796.  
  1797. This option should never be turned on by any @samp{-O} option since 
  1798. it can result in incorrect output for programs which depend on 
  1799. an exact implementation of IEEE or ANSI rules/specifications for
  1800. math functions.
  1801. @end table
  1802.  
  1803. @c following causes underfulls.. they don't look great, but we deal.
  1804. @c --mew 26jan93
  1805. The following options control specific optimizations.  The @samp{-O2}
  1806. option turns on all of these optimizations except @samp{-funroll-loops}
  1807. and @samp{-funroll-all-loops}.  On most machines, the @samp{-O} option
  1808. turns on the @samp{-fthread-jumps} and @samp{-fdelayed-branch} options,
  1809. but specific machines may handle it differently.
  1810.  
  1811. You can use the following flags in the rare cases when ``fine-tuning''
  1812. of optimizations to be performed is desired.
  1813.  
  1814. @table @code
  1815. @item -fstrength-reduce
  1816. Perform the optimizations of loop strength reduction and
  1817. elimination of iteration variables.
  1818.  
  1819. @item -fthread-jumps
  1820. Perform optimizations where we check to see if a jump branches to a
  1821. location where another comparison subsumed by the first is found.  If
  1822. so, the first branch is redirected to either the destination of the
  1823. second branch or a point immediately following it, depending on whether
  1824. the condition is known to be true or false.
  1825.  
  1826. @item -fcse-follow-jumps
  1827. In common subexpression elimination, scan through jump instructions
  1828. when the target of the jump is not reached by any other path.  For
  1829. example, when CSE encounters an @code{if} statement with an
  1830. @code{else} clause, CSE will follow the jump when the condition
  1831. tested is false.
  1832.  
  1833. @item -fcse-skip-blocks
  1834. This is similar to @samp{-fcse-follow-jumps}, but causes CSE to
  1835. follow jumps which conditionally skip over blocks.  When CSE
  1836. encounters a simple @code{if} statement with no else clause,
  1837. @samp{-fcse-skip-blocks} causes CSE to follow the jump around the
  1838. body of the @code{if}.
  1839.  
  1840. @item -frerun-cse-after-loop
  1841. Re-run common subexpression elimination after loop optimizations has been
  1842. performed.  
  1843.  
  1844. @item -fexpensive-optimizations
  1845. Perform a number of minor optimizations that are relatively expensive.
  1846.  
  1847. @item -fdelayed-branch
  1848. If supported for the target machine, attempt to reorder instructions
  1849. to exploit instruction slots available after delayed branch
  1850. instructions.
  1851.  
  1852. @item -fschedule-insns
  1853. If supported for the target machine, attempt to reorder instructions to
  1854. eliminate execution stalls due to required data being unavailable.  This
  1855. helps machines that have slow floating point or memory load instructions
  1856. by allowing other instructions to be issued until the result of the load
  1857. or floating point instruction is required.
  1858.  
  1859. @item -fschedule-insns2
  1860. Similar to @samp{-fschedule-insns}, but requests an additional pass of
  1861. instruction scheduling after register allocation has been done.  This is
  1862. especially useful on machines with a relatively small number of
  1863. registers and where memory load instructions take more than one cycle.
  1864.  
  1865. @item -fcaller-saves
  1866. Enable values to be allocated in registers that will be clobbered by
  1867. function calls, by emitting extra instructions to save and restore the
  1868. registers around such calls.  Such allocation is done only when it
  1869. seems to result in better code than would otherwise be produced.
  1870.  
  1871. This option is enabled by default on certain machines, usually those
  1872. which have no call-preserved registers to use instead.
  1873.  
  1874. @item -funroll-loops
  1875. Perform the optimization of loop unrolling.  This is only done for loops
  1876. whose number of iterations can be determined at compile time or run time.
  1877. @samp{-funroll-loop} implies both @samp{-fstrength-reduce} and
  1878. @samp{-frerun-cse-after-loop}.
  1879.  
  1880. @item -funroll-all-loops
  1881. Perform the optimization of loop unrolling.  This is done for all loops
  1882. and usually makes programs run more slowly.  @samp{-funroll-all-loops}
  1883. implies @samp{-fstrength-reduce} as well as @samp{-frerun-cse-after-loop}.
  1884.  
  1885. @item -fno-peephole
  1886. Disable any machine-specific peephole optimizations.
  1887. @end table
  1888.  
  1889. @node Preprocessor Options
  1890. @section Options Controlling the Preprocessor
  1891. @cindex preprocessor options
  1892. @cindex options, preprocessor
  1893.  
  1894. These options control the C preprocessor, which is run on each C source
  1895. file before actual compilation.
  1896.  
  1897. If you use the @samp{-E} option, nothing is done except preprocessing.
  1898. Some of these options make sense only together with @samp{-E} because
  1899. they cause the preprocessor output to be unsuitable for actual
  1900. compilation.
  1901.  
  1902. @table @code
  1903. @item -include @var{file}
  1904. Process @var{file} as input before processing the regular input file.
  1905. In effect, the contents of @var{file} are compiled first.  Any @samp{-D}
  1906. and @samp{-U} options on the command line are always processed before
  1907. @samp{-include @var{file}}, regardless of the order in which they are
  1908. written.  All the @samp{-include} and @samp{-imacros} options are
  1909. processed in the order in which they are written.
  1910.  
  1911. @item -imacros @var{file}
  1912. Process @var{file} as input, discarding the resulting output, before
  1913. processing the regular input file.  Because the output generated from
  1914. @var{file} is discarded, the only effect of @samp{-imacros @var{file}}
  1915. is to make the macros defined in @var{file} available for use in the
  1916. main input.
  1917.  
  1918. Any @samp{-D} and @samp{-U} options on the command line are always
  1919. processed before @samp{-imacros @var{file}}, regardless of the order in
  1920. which they are written.  All the @samp{-include} and @samp{-imacros}
  1921. options are processed in the order in which they are written.
  1922.  
  1923. @item -idirafter @var{dir}
  1924. @cindex second include path
  1925. Add the directory @var{dir} to the second include path.  The directories
  1926. on the second include path are searched when a header file is not found
  1927. in any of the directories in the main include path (the one that
  1928. @samp{-I} adds to).
  1929.  
  1930. @item -iprefix @var{prefix}
  1931. Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix}
  1932. options.
  1933.  
  1934. @item -iwithprefix @var{dir}
  1935. Add a directory to the second include path.  The directory's name is
  1936. made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was
  1937. specified previously with @samp{-iprefix}.  If you have not specified a
  1938. prefix yet, the directory containing the installed passes of the
  1939. compiler is used as the default.
  1940.  
  1941. @item -iwithprefixbefore @var{dir}
  1942. Add a directory to the main include path.  The directory's name is made
  1943. by concatenating @var{prefix} and @var{dir}, as in the case of
  1944. @samp{-iwithprefix}.
  1945.  
  1946. @item -isystem @var{dir}
  1947. Add a directory to the beginning of the second include path, marking it
  1948. as a system directory, so that it gets the same special treatment as
  1949. is applied to the standard system directories.
  1950.  
  1951. @item -nostdinc
  1952. Do not search the standard system directories for header files.  Only
  1953. the directories you have specified with @samp{-I} options (and the
  1954. current directory, if appropriate) are searched.  @xref{Directory
  1955. Options}, for information on @samp{-I}.
  1956.  
  1957. By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file
  1958. search path to only those directories you specify explicitly.
  1959.  
  1960. @item -undef
  1961. Do not predefine any nonstandard macros.  (Including architecture flags).
  1962.  
  1963. @item -E
  1964. Run only the C preprocessor.  Preprocess all the C source files
  1965. specified and output the results to standard output or to the
  1966. specified output file.
  1967.  
  1968. @item -C
  1969. Tell the preprocessor not to discard comments.  Used with the
  1970. @samp{-E} option.
  1971.  
  1972. @item -P
  1973. Tell the preprocessor not to generate @samp{#line} commands.
  1974. Used with the @samp{-E} option.
  1975.  
  1976. @cindex make
  1977. @cindex dependencies, make
  1978. @item -M
  1979. Tell the preprocessor to output a rule suitable for @code{make}
  1980. describing the dependencies of each object file.  For each source file,
  1981. the preprocessor outputs one @code{make}-rule whose target is the object
  1982. file name for that source file and whose dependencies are all the
  1983. @code{#include} header files it uses.  This rule may be a single line or
  1984. may be continued with @samp{\}-newline if it is long.  The list of rules
  1985. is printed on standard output instead of the preprocessed C program.
  1986.  
  1987. @samp{-M} implies @samp{-E}.
  1988.  
  1989. Another way to specify output of a @code{make} rule is by setting
  1990. the environment variable @code{DEPENDENCIES_OUTPUT} (@pxref{Environment
  1991. Variables}).
  1992.  
  1993. @item -MM
  1994. Like @samp{-M} but the output mentions only the user header files
  1995. included with @samp{#include "@var{file}"}.  System header files
  1996. included with @samp{#include <@var{file}>} are omitted.
  1997.  
  1998. @item -MD
  1999. Like @samp{-M} but the dependency information is written to a file made by
  2000. replacing ".c" with ".d" at the end of the input file names.
  2001. This is in addition to compiling the file as specified---@samp{-MD} does
  2002. not inhibit ordinary compilation the way @samp{-M} does.
  2003.  
  2004. In Mach, you can use the utility @code{md} to merge multiple dependency
  2005. files into a single dependency file suitable for using with the @samp{make}
  2006. command.
  2007.  
  2008. @item -MMD
  2009. Like @samp{-MD} except mention only user header files, not system
  2010. header files.
  2011.  
  2012. @item -MG
  2013. Treat missing header files as generated files and assume they live in the
  2014. same directory as the source file.  If you specify @samp{-MG}, you
  2015. must also specify either @samp{-M} or @samp{-MM}.  @samp{-MG} is not
  2016. supported with @samp{-MD} or @samp{-MMD}.
  2017.  
  2018. @item -H
  2019. Print the name of each header file used, in addition to other normal
  2020. activities.
  2021.  
  2022. @item -A@var{question}(@var{answer})
  2023. Assert the answer @var{answer} for @var{question}, in case it is tested
  2024. with a preprocessor conditional such as @samp{#if
  2025. #@var{question}(@var{answer})}.  @samp{-A-} disables the standard
  2026. assertions that normally describe the target machine.
  2027.  
  2028. @item -D@var{macro}
  2029. Define macro @var{macro} with the string @samp{1} as its definition.
  2030.  
  2031. @item -D@var{macro}=@var{defn}
  2032. Define macro @var{macro} as @var{defn}.  All instances of @samp{-D} on
  2033. the command line are processed before any @samp{-U} options.
  2034.  
  2035. @item -U@var{macro}
  2036. Undefine macro @var{macro}.  @samp{-U} options are evaluated after all
  2037. @samp{-D} options, but before any @samp{-include} and @samp{-imacros}
  2038. options.
  2039.  
  2040. @item -dM
  2041. Tell the preprocessor to output only a list of the macro definitions
  2042. that are in effect at the end of preprocessing.  Used with the @samp{-E}
  2043. option.
  2044.  
  2045. @item -dD
  2046. Tell the preprocessing to pass all macro definitions into the output, in
  2047. their proper sequence in the rest of the output.
  2048.  
  2049. @item -dN
  2050. Like @samp{-dD} except that the macro arguments and contents are omitted.
  2051. Only @samp{#define @var{name}} is included in the output.
  2052.  
  2053. @item -trigraphs
  2054. Support ANSI C trigraphs.  The @samp{-ansi} option also has this effect.
  2055.  
  2056. @item -Wp,@var{option}
  2057. Pass @var{option} as an option to the preprocessor.  If @var{option}
  2058. contains commas, it is split into multiple options at the commas.
  2059. @end table
  2060.  
  2061. @node Assembler Options
  2062. @section Passing Options to the Assembler
  2063.  
  2064. @c prevent bad page break with this line
  2065. You can pass options to the assembler.
  2066.  
  2067. @table @code
  2068. @item -Wa,@var{option}
  2069. Pass @var{option} as an option to the assembler.  If @var{option}
  2070. contains commas, it is split into multiple options at the commas.
  2071. @end table
  2072.  
  2073. @node Link Options
  2074. @section Options for Linking
  2075. @cindex link options
  2076. @cindex options, linking
  2077.  
  2078. These options come into play when the compiler links object files into
  2079. an executable output file.  They are meaningless if the compiler is
  2080. not doing a link step.
  2081.  
  2082. @table @code
  2083. @cindex file names
  2084. @item @var{object-file-name}
  2085. A file name that does not end in a special recognized suffix is
  2086. considered to name an object file or library.  (Object files are
  2087. distinguished from libraries by the linker according to the file
  2088. contents.)  If linking is done, these object files are used as input
  2089. to the linker.
  2090.  
  2091. @item -c
  2092. @itemx -S
  2093. @itemx -E
  2094. If any of these options is used, then the linker is not run, and
  2095. object file names should not be used as arguments.  @xref{Overall
  2096. Options}.
  2097.  
  2098. @cindex Libraries
  2099. @item -l@var{library}
  2100. Search the library named @var{library} when linking.
  2101.  
  2102. It makes a difference where in the command you write this option; the
  2103. linker searches processes libraries and object files in the order they
  2104. are specified.  Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
  2105. after file @file{foo.o} but before @file{bar.o}.  If @file{bar.o} refers
  2106. to functions in @samp{z}, those functions may not be loaded.
  2107.  
  2108. The linker searches a standard list of directories for the library,
  2109. which is actually a file named @file{lib@var{library}.a}.  The linker
  2110. then uses this file as if it had been specified precisely by name.
  2111.  
  2112. The directories searched include several standard system directories
  2113. plus any that you specify with @samp{-L}.
  2114.  
  2115. Normally the files found this way are library files---archive files
  2116. whose members are object files.  The linker handles an archive file by
  2117. scanning through it for members which define symbols that have so far
  2118. been referenced but not defined.  But if the file that is found is an
  2119. ordinary object file, it is linked in the usual fashion.  The only
  2120. difference between using an @samp{-l} option and specifying a file name
  2121. is that @samp{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
  2122. and searches several directories.
  2123.  
  2124. @item -lobjc
  2125. You need this special case of the @samp{-l} option in order to
  2126. link an Objective C program.
  2127.  
  2128. @item -nostartfiles
  2129. Do not use the standard system startup files when linking.
  2130. The standard libraries are used normally.
  2131.  
  2132. @item -nostdlib
  2133. Do not use the standard system libraries and startup files when linking.
  2134. Only the files you specify will be passed to the linker.
  2135.  
  2136. @cindex @code{-lgcc}, use with @code{-nostdlib}
  2137. @cindex @code{-nostdlib} and unresolved references
  2138. @cindex unresolved references and @code{-nostdlib}
  2139. One of the standard libraries bypassed by @samp{-nostdlib} is
  2140. @file{libgcc.a}, a library of internal subroutines that GNU CC uses to
  2141. overcome shortcomings of particular machines, or special needs for some
  2142. languages.
  2143. @ifset INTERNALS
  2144. (@xref{Interface,,Interfacing to GNU CC Output}, for more discussion of
  2145. @file{libgcc.a}.)
  2146. @end ifset
  2147. @ifclear INTERNALS
  2148. (@xref{Interface,,Interfacing to GNU CC Output,gcc.info,Porting GNU CC},
  2149. for more discussion of @file{libgcc.a}.)
  2150. @end ifclear
  2151. In most cases, you need @file{libgcc.a} even when you want to avoid
  2152. other standard libraries.  In other words, when you specify
  2153. @samp{-nostdlib} you should usually specify @samp{-lgcc} as well.  This
  2154. ensures that you have no unresolved references to internal GNU CC
  2155. library subroutines.  (For example, @samp{__main}, used to ensure C++
  2156. constructors will be called; @pxref{Collect2,,@code{collect2}}.)
  2157.  
  2158. @item -s
  2159. Remove all symbol table and relocation information from the executable.
  2160.  
  2161. @item -static
  2162. On systems that support dynamic linking, this prevents linking with the shared
  2163. libraries.  On other systems, this
  2164. option has no effect.
  2165.  
  2166. @item -shared
  2167. Produce a shared object which can then be linked with other objects to
  2168. form an executable.  Only a few systems support this option.
  2169.  
  2170. @item -symbolic
  2171. Bind references to global symbols when building a shared object.  Warn
  2172. about any unresolved references (unless overridden by the link editor
  2173. option @samp{-Xlinker -z -Xlinker defs}).  Only a few systems support
  2174. this option.
  2175.  
  2176. @item -Xlinker @var{option}
  2177. Pass @var{option} as an option to the linker.  You can use this to
  2178. supply system-specific linker options which GNU CC does not know how to
  2179. recognize.
  2180.  
  2181. If you want to pass an option that takes an argument, you must use
  2182. @samp{-Xlinker} twice, once for the option and once for the argument.
  2183. For example, to pass @samp{-assert definitions}, you must write
  2184. @samp{-Xlinker -assert -Xlinker definitions}.  It does not work to write
  2185. @samp{-Xlinker "-assert definitions"}, because this passes the entire
  2186. string as a single argument, which is not what the linker expects.
  2187.  
  2188. @item -Wl,@var{option}
  2189. Pass @var{option} as an option to the linker.  If @var{option} contains
  2190. commas, it is split into multiple options at the commas.
  2191.  
  2192. @item -u @var{symbol}
  2193. Pretend the symbol @var{symbol} is undefined, to force linking of
  2194. library modules to define it.  You can use @samp{-u} multiple times with
  2195. different symbols to force loading of additional library modules.
  2196. @end table
  2197.  
  2198. @node Directory Options
  2199. @section Options for Directory Search
  2200. @cindex directory options
  2201. @cindex options, directory search
  2202. @cindex search path
  2203.  
  2204. These options specify directories to search for header files, for
  2205. libraries and for parts of the compiler:
  2206.  
  2207. @table @code
  2208. @item -I@var{dir}
  2209. Append directory @var{dir} to the list of directories searched for
  2210. include files.
  2211.  
  2212. @item -I-
  2213. Any directories you specify with @samp{-I} options before the @samp{-I-}
  2214. option are searched only for the case of @samp{#include "@var{file}"};
  2215. they are not searched for @samp{#include <@var{file}>}.
  2216.  
  2217. If additional directories are specified with @samp{-I} options after
  2218. the @samp{-I-}, these directories are searched for all @samp{#include}
  2219. directives.  (Ordinarily @emph{all} @samp{-I} directories are used
  2220. this way.)
  2221.  
  2222. In addition, the @samp{-I-} option inhibits the use of the current
  2223. directory (where the current input file came from) as the first search
  2224. directory for @samp{#include "@var{file}"}.  There is no way to
  2225. override this effect of @samp{-I-}.  With @samp{-I.} you can specify
  2226. searching the directory which was current when the compiler was
  2227. invoked.  That is not exactly the same as what the preprocessor does
  2228. by default, but it is often satisfactory.
  2229.  
  2230. @samp{-I-} does not inhibit the use of the standard system directories
  2231. for header files.  Thus, @samp{-I-} and @samp{-nostdinc} are
  2232. independent.
  2233.  
  2234. @item -L@var{dir}
  2235. Add directory @var{dir} to the list of directories to be searched
  2236. for @samp{-l}.
  2237.  
  2238. @item -B@var{prefix}
  2239. This option specifies where to find the executables, libraries,
  2240. include files, and data files of the compiler itself.
  2241.  
  2242. The compiler driver program runs one or more of the subprograms
  2243. @file{cpp}, @file{cc1}, @file{as} and @file{ld}.  It tries
  2244. @var{prefix} as a prefix for each program it tries to run, both with and
  2245. without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
  2246.  
  2247. For each subprogram to be run, the compiler driver first tries the
  2248. @samp{-B} prefix, if any.  If that name is not found, or if @samp{-B}
  2249. was not specified, the driver tries two standard prefixes, which are
  2250. @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}.  If neither of
  2251. those results in a file name that is found, the unmodified program
  2252. name is searched for using the directories specified in your
  2253. @samp{PATH} environment variable.
  2254.  
  2255. @samp{-B} prefixes that effectively specify directory names also apply
  2256. to libraries in the linker, because the compiler translates these
  2257. options into @samp{-L} options for the linker.  They also apply to
  2258. includes files in the preprocessor, because the compiler translates these
  2259. options into @samp{-isystem} options for the preprocessor.  In this case,
  2260. the compiler appends @samp{include} to the prefix.
  2261.  
  2262. The run-time support file @file{libgcc.a} can also be searched for using
  2263. the @samp{-B} prefix, if needed.  If it is not found there, the two
  2264. standard prefixes above are tried, and that is all.  The file is left
  2265. out of the link if it is not found by those means.
  2266.  
  2267. Another way to specify a prefix much like the @samp{-B} prefix is to use
  2268. the environment variable @code{GCC_EXEC_PREFIX}.  @xref{Environment
  2269. Variables}.
  2270. @end table
  2271.  
  2272. @node Target Options
  2273. @section Specifying Target Machine and Compiler Version
  2274. @cindex target options
  2275. @cindex cross compiling
  2276. @cindex specifying machine version
  2277. @cindex specifying compiler version and target machine
  2278. @cindex compiler version, specifying
  2279. @cindex target machine, specifying
  2280.  
  2281. By default, GNU CC compiles code for the same type of machine that you
  2282. are using.  However, it can also be installed as a cross-compiler, to
  2283. compile for some other type of machine.  In fact, several different
  2284. configurations of GNU CC, for different target machines, can be
  2285. installed side by side.  Then you specify which one to use with the
  2286. @samp{-b} option.
  2287.  
  2288. In addition, older and newer versions of GNU CC can be installed side
  2289. by side.  One of them (probably the newest) will be the default, but
  2290. you may sometimes wish to use another.
  2291.  
  2292. @table @code
  2293. @item -b @var{machine}
  2294. The argument @var{machine} specifies the target machine for compilation.
  2295. This is useful when you have installed GNU CC as a cross-compiler.
  2296.  
  2297. The value to use for @var{machine} is the same as was specified as the
  2298. machine type when configuring GNU CC as a cross-compiler.  For
  2299. example, if a cross-compiler was configured with @samp{configure
  2300. i386v}, meaning to compile for an 80386 running System V, then you
  2301. would specify @samp{-b i386v} to run that cross compiler.
  2302.  
  2303. When you do not specify @samp{-b}, it normally means to compile for
  2304. the same type of machine that you are using.
  2305.  
  2306. @item -V @var{version}
  2307. The argument @var{version} specifies which version of GNU CC to run.
  2308. This is useful when multiple versions are installed.  For example,
  2309. @var{version} might be @samp{2.0}, meaning to run GNU CC version 2.0.
  2310.  
  2311. The default version, when you do not specify @samp{-V}, is controlled
  2312. by the way GNU CC is installed.  Normally, it will be a version that
  2313. is recommended for general use.
  2314. @end table
  2315.  
  2316. The @samp{-b} and @samp{-V} options actually work by controlling part of
  2317. the file name used for the executable files and libraries used for
  2318. compilation.  A given version of GNU CC, for a given target machine, is
  2319. normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}.@refill
  2320.  
  2321. Thus, sites can customize the effect of @samp{-b} or @samp{-V} either by
  2322. changing the names of these directories or adding alternate names (or
  2323. symbolic links).  If in directory @file{/usr/local/lib/gcc-lib/} the
  2324. file @file{80386} is a link to the file @file{i386v}, then @samp{-b
  2325. 80386} becomes an alias for @samp{-b i386v}.
  2326.  
  2327. In one respect, the @samp{-b} or @samp{-V} do not completely change
  2328. to a different compiler: the top-level driver program @code{gcc}
  2329. that you originally invoked continues to run and invoke the other
  2330. executables (preprocessor, compiler per se, assembler and linker)
  2331. that do the real work.  However, since no real work is done in the
  2332. driver program, it usually does not matter that the driver program
  2333. in use is not the one for the specified target and version.
  2334.  
  2335. The only way that the driver program depends on the target machine is
  2336. in the parsing and handling of special machine-specific options.
  2337. However, this is controlled by a file which is found, along with the
  2338. other executables, in the directory for the specified version and
  2339. target machine.  As a result, a single installed driver program adapts
  2340. to any specified target machine and compiler version.
  2341.  
  2342. The driver program executable does control one significant thing,
  2343. however: the default version and target machine.  Therefore, you can
  2344. install different instances of the driver program, compiled for
  2345. different targets or versions, under different names.
  2346.  
  2347. For example, if the driver for version 2.0 is installed as @code{ogcc}
  2348. and that for version 2.1 is installed as @code{gcc}, then the command
  2349. @code{gcc} will use version 2.1 by default, while @code{ogcc} will use
  2350. 2.0 by default.  However, you can choose either version with either
  2351. command with the @samp{-V} option.
  2352.  
  2353. @node Submodel Options
  2354. @section Hardware Models and Configurations
  2355. @cindex submodel options
  2356. @cindex specifying hardware config
  2357. @cindex hardware models and configurations, specifying
  2358. @cindex machine dependent options
  2359.  
  2360. Earlier we discussed the standard option @samp{-b} which chooses among
  2361. different installed compilers for completely different target
  2362. machines, such as Vax vs. 68000 vs. 80386.
  2363.  
  2364. In addition, each of these target machine types can have its own
  2365. special options, starting with @samp{-m}, to choose among various
  2366. hardware models or configurations---for example, 68010 vs 68020,
  2367. floating coprocessor or none.  A single installed version of the
  2368. compiler can compile for any model or configuration, according to the
  2369. options specified.
  2370.  
  2371. Some configurations of the compiler also support additional special
  2372. options, usually for compatibility with other compilers on the same
  2373. platform.
  2374.  
  2375. @ifset INTERNALS
  2376. These options are defined by the macro @code{TARGET_SWITCHES} in the
  2377. machine description.  The default for the options is also defined by
  2378. that macro, which enables you to change the defaults.
  2379. @end ifset
  2380.  
  2381. @menu
  2382. * M680x0 Options::
  2383. * VAX Options::
  2384. * SPARC Options::
  2385. * Convex Options::
  2386. * AMD29K Options::
  2387. * ARM Options::
  2388. * M88K Options::
  2389. * RS/6000 and PowerPC Options::
  2390. * RT Options::
  2391. * MIPS Options::
  2392. * i386 Options::
  2393. * HPPA Options::
  2394. * Intel 960 Options::
  2395. * DEC Alpha Options::
  2396. * Clipper Options::
  2397. * H8/300 Options::
  2398. * System V Options::
  2399. @end menu
  2400.  
  2401. @node M680x0 Options
  2402. @subsection M680x0 Options
  2403. @cindex M680x0 options
  2404.  
  2405. These are the @samp{-m} options defined for the 68000 series.  The default
  2406. values for these options depends on which style of 68000 was selected when
  2407. the compiler was configured; the defaults for the most common choices are
  2408. given below.
  2409.  
  2410. @table @code
  2411. @item -m68000
  2412. @itemx -mc68000
  2413. Generate output for a 68000.  This is the default
  2414. when the compiler is configured for 68000-based systems.
  2415.  
  2416. @item -m68020
  2417. @itemx -mc68020
  2418. Generate output for a 68020.  This is the default
  2419. when the compiler is configured for 68020-based systems.
  2420.  
  2421. @item -m68881
  2422. Generate output containing 68881 instructions for floating point.
  2423. This is the default for most 68020 systems unless @samp{-nfp} was
  2424. specified when the compiler was configured.
  2425.  
  2426. @item -m68030
  2427. Generate output for a 68030.  This is the default when the compiler is
  2428. configured for 68030-based systems.
  2429.  
  2430. @item -m68040
  2431. Generate output for a 68040.  This is the default when the compiler is
  2432. configured for 68040-based systems.
  2433.  
  2434. This option inhibits the use of 68881/68882 instructions that have to be
  2435. emulated by software on the 68040.  If your 68040 does not have code to
  2436. emulate those instructions, use @samp{-m68040}.
  2437.  
  2438. @item -m68020-40
  2439. Generate output for a 68040, without using any of the new instructions.
  2440. This results in code which can run relatively efficiently on either a
  2441. 68020/68881 or a 68030 or a 68040.  The generated code does use the
  2442. 68881 instructions that are emulated on the 68040.
  2443.  
  2444. @item -mfpa
  2445. Generate output containing Sun FPA instructions for floating point.
  2446.  
  2447. @item -msoft-float
  2448. Generate output containing library calls for floating point.
  2449. @strong{Warning:} the requisite libraries are not part of GNU CC.
  2450. Normally the facilities of the machine's usual C compiler are used, but
  2451. this can't be done directly in cross-compilation.  You must make your
  2452. own arrangements to provide suitable library functions for
  2453. cross-compilation.
  2454.  
  2455. @item -mshort
  2456. Consider type @code{int} to be 16 bits wide, like @code{short int}.
  2457.  
  2458. @item -mnobitfield
  2459. Do not use the bit-field instructions.  The @samp{-m68000} option
  2460. implies @w{@samp{-mnobitfield}}.
  2461.  
  2462. @item -mbitfield
  2463. Do use the bit-field instructions.  The @samp{-m68020} option implies
  2464. @samp{-mbitfield}.  This is the default if you use a configuration
  2465. designed for a 68020.
  2466.  
  2467. @item -mrtd
  2468. Use a different function-calling convention, in which functions
  2469. that take a fixed number of arguments return with the @code{rtd}
  2470. instruction, which pops their arguments while returning.  This
  2471. saves one instruction in the caller since there is no need to pop
  2472. the arguments there.
  2473.  
  2474. This calling convention is incompatible with the one normally
  2475. used on Unix, so you cannot use it if you need to call libraries
  2476. compiled with the Unix compiler.
  2477.  
  2478. Also, you must provide function prototypes for all functions that
  2479. take variable numbers of arguments (including @code{printf});
  2480. otherwise incorrect code will be generated for calls to those
  2481. functions.
  2482.  
  2483. In addition, seriously incorrect code will result if you call a
  2484. function with too many arguments.  (Normally, extra arguments are
  2485. harmlessly ignored.)
  2486.  
  2487. The @code{rtd} instruction is supported by the 68010 and 68020
  2488. processors, but not by the 68000.
  2489. @end table
  2490.  
  2491. @node VAX Options
  2492. @subsection VAX Options
  2493. @cindex VAX options
  2494.  
  2495. These @samp{-m} options are defined for the Vax:
  2496.  
  2497. @table @code
  2498. @item -munix
  2499. Do not output certain jump instructions (@code{aobleq} and so on)
  2500. that the Unix assembler for the Vax cannot handle across long
  2501. ranges.
  2502.  
  2503. @item -mgnu
  2504. Do output those jump instructions, on the assumption that you
  2505. will assemble with the GNU assembler.
  2506.  
  2507. @item -mg
  2508. Output code for g-format floating point numbers instead of d-format.
  2509. @end table
  2510.  
  2511. @node SPARC Options
  2512. @subsection SPARC Options
  2513. @cindex SPARC options
  2514.  
  2515. These @samp{-m} switches are supported on the SPARC:
  2516.  
  2517. @table @code
  2518. @item -mno-app-regs
  2519. @itemx -mapp-regs
  2520. Specify @samp{-mapp-regs} to generate output using the global registers
  2521. 2 through 4, which the SPARC SVR4 ABI reserves for applications.  This
  2522. is the default.
  2523.  
  2524. To be fully SVR4 ABI compliant at the cost of some performance loss,
  2525. specify @samp{-mno-app-regs}.  You should compile libraries and system
  2526. software with this option.
  2527.  
  2528. @item -mfpu
  2529. @itemx -mhard-float
  2530. Generate output containing floating point instructions.  This is the
  2531. default.
  2532.  
  2533. @item -mno-fpu
  2534. @itemx -msoft-float
  2535. Generate output containing library calls for floating point.
  2536. @strong{Warning:} there is no GNU floating-point library for SPARC.
  2537. Normally the facilities of the machine's usual C compiler are used, but
  2538. this cannot be done directly in cross-compilation.  You must make your
  2539. own arrangements to provide suitable library functions for
  2540. cross-compilation.
  2541.  
  2542. @samp{-msoft-float} changes the calling convention in the output file;
  2543. therefore, it is only useful if you compile @emph{all} of a program with
  2544. this option.  In particular, you need to compile @file{libgcc.a}, the
  2545. library that comes with GNU CC, with @samp{-msoft-float} in order for
  2546. this to work.
  2547.  
  2548. @item -mhard-quad-float
  2549. Generate output containing quad-word (long double) floating point
  2550. instructions.
  2551.  
  2552. @item -msoft-quad-float
  2553. Generate output containing library calls for quad-word (long double)
  2554. floating point instructions.  The functions called are those specified
  2555. in the SPARC ABI.  This is the default.
  2556.  
  2557. As of this writing, there are no sparc implementations that have hardware
  2558. support for the quad-word floating point instructions.  They all invoke
  2559. a trap handler for one of these instructions, and then the trap handler
  2560. emulates the effect of the instruction.  Because of the trap handler overhead,
  2561. this is much slower than calling the ABI library routines.  Thus the
  2562. @samp{-msoft-quad-float} option is the default.
  2563.  
  2564. @item -mno-epilogue
  2565. @itemx -mepilogue
  2566. With @samp{-mepilogue} (the default), the compiler always emits code for
  2567. function exit at the end of each function.  Any function exit in
  2568. the middle of the function (such as a return statement in C) will
  2569. generate a jump to the exit code at the end of the function.
  2570.  
  2571. With @samp{-mno-epilogue}, the compiler tries to emit exit code inline
  2572. at every function exit.
  2573.  
  2574. @item -mno-flat
  2575. @itemx -mflat
  2576. With @samp{-mflat}, the compiler does not generate save/restore instructions
  2577. and will use a "flat" or single register window calling convention.
  2578. This model uses %i7 as the frame pointer and is compatible with the normal
  2579. register window model.  Code from either may be intermixed although
  2580. debugger support is still incomplete.  The local registers and the input
  2581. registers (0-5) are still treated as "call saved" registers and will be
  2582. saved on the stack as necessary.
  2583.  
  2584. With @samp{-mno-flat} (the default), the compiler emits save/restore
  2585. instructions (except for leaf functions) and is the normal mode of operation.
  2586.  
  2587. @item -mno-unaligned-doubles
  2588. @itemx -munaligned-doubles
  2589. Assume that doubles have 8 byte alignment.  This is the default.
  2590.  
  2591. With @samp{-munaligned-doubles}, GNU CC assumes that doubles have 8 byte
  2592. alignment only if they are contained in another type, or if they have an
  2593. absolute address.  Otherwise, it assumes they have 4 byte alignment.
  2594. Specifying this option avoids some rare compatibility problems with code
  2595. generated by other compilers.  It is not the default because it results
  2596. in a performance loss, especially for floating point code.
  2597.  
  2598. @item -mv8
  2599. @itemx -msparclite
  2600. These two options select variations on the SPARC architecture.
  2601.  
  2602. By default (unless specifically configured for the Fujitsu SPARClite),
  2603. GCC generates code for the v7 variant of the SPARC architecture.
  2604.  
  2605. @samp{-mv8} will give you SPARC v8 code.  The only difference from v7
  2606. code is that the compiler emits the integer multiply and integer
  2607. divide instructions which exist in SPARC v8 but not in SPARC v7.
  2608.  
  2609. @samp{-msparclite} will give you SPARClite code.  This adds the integer
  2610. multiply, integer divide step and scan (@code{ffs}) instructions which
  2611. exist in SPARClite but not in SPARC v7.
  2612.  
  2613. @item -mcypress
  2614. @itemx -msupersparc
  2615. These two options select the processor for which the code is optimised.
  2616.  
  2617. With @samp{-mcypress} (the default), the compiler optimizes code for the
  2618. Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series.
  2619. This is also apropriate for the older SparcStation 1, 2, IPX etc.
  2620.  
  2621. With @samp{-msupersparc} the compiler optimizes code for the SuperSparc cpu, as
  2622. used in the SparcStation 10, 1000 and 2000 series. This flag also enables use
  2623. of the full SPARC v8 instruction set.
  2624. @end table
  2625.  
  2626. In a future version of GCC, these options will very likely be
  2627. renamed to @samp{-mcpu=cypress} and @samp{-mcpu=supersparc}.
  2628.  
  2629. These @samp{-m} switches are supported in addition to the above
  2630. on SPARC V9 processors:
  2631.  
  2632. @table @code
  2633. @item -mmedlow
  2634. Generate code for the Medium/Low code model: assume a 32 bit address space.
  2635. Programs are statically linked, PIC is not supported.  Pointers are still
  2636. 64 bits.
  2637.  
  2638. It is very likely that a future version of GCC will rename this option.
  2639.  
  2640. @item -mmedany
  2641. Generate code for the Medium/Anywhere code model: assume a 32 bit text
  2642. segment starting at offset 0, and a 32 bit data segment starting anywhere
  2643. (determined at link time).  Programs are statically linked, PIC is not
  2644. supported.  Pointers are still 64 bits.
  2645.  
  2646. It is very likely that a future version of GCC will rename this option.
  2647.  
  2648. @item -mint64
  2649. Types long and int are 64 bits.
  2650.  
  2651. @item -mlong32
  2652. Types long and int are 32 bits.
  2653.  
  2654. @item -mlong64
  2655. @itemx -mint32
  2656. Type long is 64 bits, and type int is 32 bits.
  2657.  
  2658. @item -mstack-bias
  2659. @itemx -mno-stack-bias
  2660. With @samp{-mstack-bias}, GNU CC assumes that the stack pointer, and
  2661. frame pointer if present, are offset by -2047 which must be added back
  2662. when making stack frame references.
  2663. Otherwise, assume no such offset is present.
  2664. @end table
  2665.  
  2666. @node Convex Options
  2667. @subsection Convex Options
  2668. @cindex Convex options
  2669.  
  2670. These @samp{-m} options are defined for Convex:
  2671.  
  2672. @table @code
  2673. @item -mc1
  2674. Generate output for C1.  The code will run on any Convex machine.
  2675. The preprocessor symbol @code{__convex__c1__} is defined.
  2676.  
  2677. @item -mc2
  2678. Generate output for C2.  Uses instructions not available on C1.
  2679. Scheduling and other optimizations are chosen for max performance on C2.
  2680. The preprocessor symbol @code{__convex_c2__} is defined.
  2681.  
  2682. @item -mc32
  2683. Generate output for C32xx.  Uses instructions not available on C1.
  2684. Scheduling and other optimizations are chosen for max performance on C32.
  2685. The preprocessor symbol @code{__convex_c32__} is defined.
  2686.  
  2687. @item -mc34
  2688. Generate output for C34xx.  Uses instructions not available on C1.
  2689. Scheduling and other optimizations are chosen for max performance on C34.
  2690. The preprocessor symbol @code{__convex_c34__} is defined.
  2691.  
  2692. @item -mc38
  2693. Generate output for C38xx.  Uses instructions not available on C1.
  2694. Scheduling and other optimizations are chosen for max performance on C38.
  2695. The preprocessor symbol @code{__convex_c38__} is defined.
  2696.  
  2697. @item -margcount
  2698. Generate code which puts an argument count in the word preceding each
  2699. argument list.  This is compatible with regular CC, and a few programs
  2700. may need the argument count word.  GDB and other source-level debuggers
  2701. do not need it; this info is in the symbol table.
  2702.  
  2703. @item -mnoargcount
  2704. Omit the argument count word.  This is the default.
  2705.  
  2706. @item -mvolatile-cache
  2707. Allow volatile references to be cached.  This is the default.
  2708.  
  2709. @item -mvolatile-nocache
  2710. Volatile references bypass the data cache, going all the way to memory.
  2711. This is only needed for multi-processor code that does not use standard
  2712. synchronization instructions.  Making non-volatile references to volatile
  2713. locations will not necessarily work.
  2714.  
  2715. @item -mlong32
  2716. Type long is 32 bits, the same as type int.  This is the default.
  2717.  
  2718. @item -mlong64
  2719. Type long is 64 bits, the same as type long long.  This option is useless,
  2720. because no library support exists for it.
  2721. @end table
  2722.  
  2723. @node AMD29K Options
  2724. @subsection AMD29K Options
  2725. @cindex AMD29K options
  2726.  
  2727. These @samp{-m} options are defined for the AMD Am29000:
  2728.  
  2729. @table @code
  2730. @item -mdw
  2731. @kindex -mdw
  2732. @cindex DW bit (29k)
  2733. Generate code that assumes the @code{DW} bit is set, i.e., that byte and
  2734. halfword operations are directly supported by the hardware.  This is the
  2735. default.
  2736.  
  2737. @item -mndw
  2738. @kindex -mndw
  2739. Generate code that assumes the @code{DW} bit is not set.
  2740.  
  2741. @item -mbw
  2742. @kindex -mbw
  2743. @cindex byte writes (29k)
  2744. Generate code that assumes the system supports byte and halfword write
  2745. operations.  This is the default.
  2746.  
  2747. @item -mnbw
  2748. @kindex -mnbw
  2749. Generate code that assumes the systems does not support byte and
  2750. halfword write operations.  @samp{-mnbw} implies @samp{-mndw}.
  2751.  
  2752. @item -msmall
  2753. @kindex -msmall
  2754. @cindex memory model (29k)
  2755. Use a small memory model that assumes that all function addresses are
  2756. either within a single 256 KB segment or at an absolute address of less
  2757. than 256k.  This allows the @code{call} instruction to be used instead
  2758. of a @code{const}, @code{consth}, @code{calli} sequence.
  2759.  
  2760. @item -mnormal
  2761. @kindex -mnormal
  2762. Use the normal memory model: Generate @code{call} instructions only when
  2763. calling functions in the same file and @code{calli} instructions
  2764. otherwise.  This works if each file occupies less than 256 KB but allows
  2765. the entire executable to be larger than 256 KB.  This is the default.
  2766.  
  2767. @item -mlarge
  2768. Always use @code{calli} instructions.  Specify this option if you expect
  2769. a single file to compile into more than 256 KB of code.
  2770.  
  2771. @item -m29050
  2772. @kindex -m29050
  2773. @cindex processor selection (29k)
  2774. Generate code for the Am29050.
  2775.  
  2776. @item -m29000
  2777. @kindex -m29000
  2778. Generate code for the Am29000.  This is the default.
  2779.  
  2780. @item -mkernel-registers
  2781. @kindex -mkernel-registers
  2782. @cindex kernel and user registers (29k)
  2783. Generate references to registers @code{gr64-gr95} instead of to
  2784. registers @code{gr96-gr127}.  This option can be used when compiling
  2785. kernel code that wants a set of global registers disjoint from that used
  2786. by user-mode code.
  2787.  
  2788. Note that when this option is used, register names in @samp{-f} flags
  2789. must use the normal, user-mode, names.
  2790.  
  2791. @item -muser-registers
  2792. @kindex -muser-registers
  2793. Use the normal set of global registers, @code{gr96-gr127}.  This is the
  2794. default.
  2795.  
  2796. @item -mstack-check
  2797. @itemx -mno-stack-check
  2798. @kindex -mstack-check
  2799. @cindex stack checks (29k)
  2800. Insert (or do not insert) a call to @code{__msp_check} after each stack
  2801. adjustment.  This is often used for kernel code.
  2802.  
  2803. @item -mstorem-bug
  2804. @itemx -mno-storem-bug
  2805. @kindex -mstorem-bug
  2806. @cindex storem bug (29k)
  2807. @samp{-mstorem-bug} handles 29k processors which cannot handle the
  2808. separation of a mtsrim insn and a storem instruction (most 29000 chips
  2809. to date, but not the 29050).
  2810.  
  2811. @item -mno-reuse-arg-regs
  2812. @itemx -mreuse-arg-regs
  2813. @kindex -mreuse-arg-regs
  2814. @samp{-mno-reuse-arg-regs} tells the compiler to only use incoming argument
  2815. registers for copying out arguments.  This helps detect calling a function
  2816. with fewer arguments than it was declared with.
  2817.  
  2818. @item -msoft-float
  2819. @kindex -msoft-float
  2820. Generate output containing library calls for floating point.
  2821. @strong{Warning:} the requisite libraries are not part of GNU CC.
  2822. Normally the facilities of the machine's usual C compiler are used, but
  2823. this can't be done directly in cross-compilation.  You must make your
  2824. own arrangements to provide suitable library functions for
  2825. cross-compilation.
  2826. @end table
  2827.  
  2828. @node ARM Options
  2829. @subsection ARM Options
  2830. @cindex ARM options
  2831.  
  2832. These @samp{-m} options are defined for Advanced RISC Machines (ARM)
  2833. architectures:
  2834.  
  2835. @table @code
  2836. @item -m2
  2837. @itemx -m3
  2838. @kindex -m2
  2839. @kindex -m3
  2840. These options are identical.  Generate code for the ARM2 and ARM3
  2841. processors.  This option is the default.  You should also use this
  2842. option to generate code for ARM6 processors that are running with a
  2843. 26-bit program counter.
  2844.  
  2845. @item -m6
  2846. @kindex -m6
  2847. Generate code for the ARM6 processor when running with a 32-bit program
  2848. counter.
  2849.  
  2850. @item -mapcs
  2851. @kindex -mapcs
  2852. Generate a stack frame that is compliant with the ARM Proceedure Call 
  2853. Standard for all functions, even if this is not strictly necessary for
  2854. correct execution of the code.
  2855.  
  2856. @item -mbsd
  2857. @kindex -mbsd
  2858. This option only applies to RISC iX.  Emulate the native BSD-mode
  2859. compiler.  This is the default if @samp{-ansi} is not specified.
  2860.  
  2861. @item -mxopen
  2862. @kindex -mxopen
  2863. This option only applies to RISC iX.  Emulate the native X/Open-mode
  2864. compiler.
  2865.  
  2866. @item -mno-symrename
  2867. @kindex -mno-symrename
  2868. This option only applies to RISC iX.  Do not run the assembler
  2869. post-processor, @samp{symrename}, after code has been assembled.
  2870. Normally it is necessary to modify some of the standard symbols in
  2871. preparation for linking with the RISC iX C library; this option
  2872. suppresses this pass.  The post-processor is never run when the
  2873. compiler is built for cross-compilation.
  2874. @end table
  2875.  
  2876. @node M88K Options
  2877. @subsection M88K Options
  2878. @cindex M88k options
  2879.  
  2880. These @samp{-m} options are defined for Motorola 88k architectures:
  2881.  
  2882. @table @code
  2883. @item -m88000
  2884. @kindex -m88000
  2885. Generate code that works well on both the m88100 and the
  2886. m88110.
  2887.  
  2888. @item -m88100
  2889. @kindex -m88100
  2890. Generate code that works best for the m88100, but that also
  2891. runs on the m88110.
  2892.  
  2893. @item -m88110
  2894. @kindex -m88110
  2895. Generate code that works best for the m88110, and may not run
  2896. on the m88100.
  2897.  
  2898. @item -mbig-pic
  2899. @kindex -mbig-pic
  2900. Obsolete option to be removed from the next revision.
  2901. Use @samp{-fPIC}.
  2902.  
  2903. @item -midentify-revision
  2904. @kindex -midentify-revision
  2905. @kindex ident
  2906. @cindex identifying source, compiler (88k)
  2907. Include an @code{ident} directive in the assembler output recording the
  2908. source file name, compiler name and version, timestamp, and compilation
  2909. flags used.
  2910.  
  2911. @item -mno-underscores
  2912. @kindex -mno-underscores
  2913. @cindex underscores, avoiding (88k)
  2914. In assembler output, emit symbol names without adding an underscore
  2915. character at the beginning of each name.  The default is to use an
  2916. underscore as prefix on each name.
  2917.  
  2918. @item -mocs-debug-info
  2919. @itemx -mno-ocs-debug-info
  2920. @kindex -mocs-debug-info
  2921. @kindex -mno-ocs-debug-info
  2922. @cindex OCS (88k)
  2923. @cindex debugging, 88k OCS
  2924. Include (or omit) additional debugging information (about registers used
  2925. in each stack frame) as specified in the 88open Object Compatibility
  2926. Standard, ``OCS''.  This extra information allows debugging of code that
  2927. has had the frame pointer eliminated.  The default for DG/UX, SVr4, and
  2928. Delta 88 SVr3.2 is to include this information; other 88k configurations
  2929. omit this information by default.
  2930.  
  2931. @item -mocs-frame-position
  2932. @kindex -mocs-frame-position
  2933. @cindex register positions in frame (88k)
  2934. When emitting COFF debugging information for automatic variables and
  2935. parameters stored on the stack, use the offset from the canonical frame
  2936. address, which is the stack pointer (register 31) on entry to the
  2937. function.  The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use
  2938. @samp{-mocs-frame-position}; other 88k configurations have the default
  2939. @samp{-mno-ocs-frame-position}.
  2940.  
  2941. @item -mno-ocs-frame-position
  2942. @kindex -mno-ocs-frame-position
  2943. @cindex register positions in frame (88k)
  2944. When emitting COFF debugging information for automatic variables and
  2945. parameters stored on the stack, use the offset from the frame pointer
  2946. register (register 30).  When this option is in effect, the frame
  2947. pointer is not eliminated when debugging information is selected by the
  2948. -g switch.
  2949.  
  2950. @item -moptimize-arg-area
  2951. @itemx -mno-optimize-arg-area
  2952. @kindex -moptimize-arg-area
  2953. @kindex -mno-optimize-arg-area
  2954. @cindex arguments in frame (88k)
  2955. Control how function arguments are stored in stack frames.
  2956. @samp{-moptimize-arg-area} saves space by optimizing them, but this
  2957. conflicts with the 88open specifications.  The opposite alternative,
  2958. @samp{-mno-optimize-arg-area}, agrees with 88open standards.  By default
  2959. GNU CC does not optimize the argument area.
  2960.  
  2961. @item -mshort-data-@var{num}
  2962. @kindex -mshort-data-@var{num}
  2963. @cindex smaller data references (88k)
  2964. @cindex r0-relative references (88k)
  2965. Generate smaller data references by making them relative to @code{r0},
  2966. which allows loading a value using a single instruction (rather than the
  2967. usual two).  You control which data references are affected by
  2968. specifying @var{num} with this option.  For example, if you specify
  2969. @samp{-mshort-data-512}, then the data references affected are those
  2970. involving displacements of less than 512 bytes.
  2971. @samp{-mshort-data-@var{num}} is not effective for @var{num} greater
  2972. than 64k.
  2973.  
  2974. @item -mserialize-volatile
  2975. @kindex -mserialize-volatile
  2976. @itemx -mno-serialize-volatile
  2977. @kindex -mno-serialize-volatile
  2978. @cindex sequential consistency on 88k
  2979. Do, or don't, generate code to guarantee sequential consistency
  2980. of volatile memory references.  By default, consistency is
  2981. guaranteed.
  2982.  
  2983. The order of memory references made by the MC88110 processor does
  2984. not always match the order of the instructions requesting those
  2985. references.  In particular, a load instruction may execute before
  2986. a preceding store instruction.  Such reordering violates
  2987. sequential consistency of volatile memory references, when there
  2988. are multiple processors.   When consistency must be guaranteed,
  2989. GNU C generates special instructions, as needed, to force
  2990. execution in the proper order.
  2991.  
  2992. The MC88100 processor does not reorder memory references and so
  2993. always provides sequential consistency.  However, by default, GNU
  2994. C generates the special instructions to guarantee consistency
  2995. even when you use @samp{-m88100}, so that the code may be run on an
  2996. MC88110 processor.  If you intend to run your code only on the
  2997. MC88100 processor, you may use @samp{-mno-serialize-volatile}.
  2998.  
  2999. The extra code generated to guarantee consistency may affect the
  3000. performance of your application.  If you know that you can safely
  3001. forgo this guarantee, you may use @samp{-mno-serialize-volatile}.
  3002.  
  3003. @item -msvr4
  3004. @itemx -msvr3
  3005. @kindex -msvr4
  3006. @kindex -msvr3
  3007. @cindex assembler syntax, 88k
  3008. @cindex SVr4
  3009. Turn on (@samp{-msvr4}) or off (@samp{-msvr3}) compiler extensions
  3010. related to System V release 4 (SVr4).  This controls the following:
  3011.  
  3012. @enumerate
  3013. @item 
  3014. Which variant of the assembler syntax to emit.
  3015. @item
  3016. @samp{-msvr4} makes the C preprocessor recognize @samp{#pragma weak}
  3017. that is used on System V release 4.
  3018. @item
  3019. @samp{-msvr4} makes GNU CC issue additional declaration directives used in
  3020. SVr4.  
  3021. @end enumerate
  3022.  
  3023. @samp{-msvr4} is the default for the m88k-motorola-sysv4 and
  3024. m88k-dg-dgux m88k configurations. @samp{-msvr3} is the default for all
  3025. other m88k configurations.
  3026.  
  3027. @item -mversion-03.00
  3028. @kindex -mversion-03.00
  3029. This option is obsolete, and is ignored.
  3030. @c ??? which asm syntax better for GAS?  option there too?
  3031.  
  3032. @item -mno-check-zero-division
  3033. @itemx -mcheck-zero-division
  3034. @kindex -mno-check-zero-division
  3035. @kindex -mcheck-zero-division
  3036. @cindex zero division on 88k
  3037. Do, or don't, generate code to guarantee that integer division by
  3038. zero will be detected.  By default, detection is guaranteed.
  3039.  
  3040. Some models of the MC88100 processor fail to trap upon integer
  3041. division by zero under certain conditions.  By default, when
  3042. compiling code that might be run on such a processor, GNU C
  3043. generates code that explicitly checks for zero-valued divisors
  3044. and traps with exception number 503 when one is detected.  Use of
  3045. mno-check-zero-division suppresses such checking for code
  3046. generated to run on an MC88100 processor.
  3047.  
  3048. GNU C assumes that the MC88110 processor correctly detects all
  3049. instances of integer division by zero.  When @samp{-m88110} is
  3050. specified, both @samp{-mcheck-zero-division} and
  3051. @samp{-mno-check-zero-division} are ignored, and no explicit checks for
  3052. zero-valued divisors are generated. 
  3053.  
  3054. @item -muse-div-instruction
  3055. @kindex -muse-div-instruction
  3056. @cindex divide instruction, 88k
  3057. Use the div instruction for signed integer division on the
  3058. MC88100 processor.  By default, the div instruction is not used.
  3059.  
  3060. On the MC88100 processor the signed integer division instruction
  3061. div) traps to the operating system on a negative operand.  The
  3062. operating system transparently completes the operation, but at a
  3063. large cost in execution time.  By default, when compiling code
  3064. that might be run on an MC88100 processor, GNU C emulates signed
  3065. integer division using the unsigned integer division instruction
  3066. divu), thereby avoiding the large penalty of a trap to the
  3067. operating system.  Such emulation has its own, smaller, execution
  3068. cost in both time and space.  To the extent that your code's
  3069. important signed integer division operations are performed on two
  3070. nonnegative operands, it may be desirable to use the div
  3071. instruction directly.
  3072.  
  3073. On the MC88110 processor the div instruction (also known as the
  3074. divs instruction) processes negative operands without trapping to
  3075. the operating system.  When @samp{-m88110} is specified,
  3076. @samp{-muse-div-instruction} is ignored, and the div instruction is used
  3077. for signed integer division.
  3078.  
  3079. Note that the result of dividing INT_MIN by -1 is undefined.  In
  3080. particular, the behavior of such a division with and without
  3081. @samp{-muse-div-instruction}  may differ.
  3082.  
  3083. @item -mtrap-large-shift
  3084. @itemx -mhandle-large-shift
  3085. @kindex -mtrap-large-shift
  3086. @kindex -mhandle-large-shift
  3087. @cindex bit shift overflow (88k)
  3088. @cindex large bit shifts (88k)
  3089. Include code to detect bit-shifts of more than 31 bits; respectively,
  3090. trap such shifts or emit code to handle them properly.  By default GNU CC
  3091. makes no special provision for large bit shifts.
  3092.  
  3093. @item -mwarn-passed-structs
  3094. @kindex -mwarn-passed-structs
  3095. @cindex structure passing (88k)
  3096. Warn when a function passes a struct as an argument or result.
  3097. Structure-passing conventions have changed during the evolution of the C
  3098. language, and are often the source of portability problems.  By default,
  3099. GNU CC issues no such warning.
  3100. @end table
  3101.  
  3102. @node RS/6000 and PowerPC Options
  3103. @subsection IBM RS/6000 and PowerPC Options
  3104. @cindex RS/6000 and PowerPC Options
  3105. @cindex IBM RS/6000 and PowerPC Options
  3106.  
  3107. These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
  3108. @table @code
  3109. @item -mpower
  3110. @itemx -mno-power
  3111. @itemx -mpower2
  3112. @itemx -mno-power2
  3113. @itemx -mpowerpc
  3114. @itemx -mno-powerpc
  3115. @itemx -mpowerpc-gpopt
  3116. @itemx -mno-powerpc-gpopt
  3117. @itemx -mpowerpc-gfxopt
  3118. @itemx -mno-powerpc-gfxopt
  3119. @kindex -mpower
  3120. @kindex -mpower2
  3121. @kindex -mpowerpc
  3122. @kindex -mpowerpc-gpopt
  3123. @kindex -mpowerpc-gfxopt
  3124. GNU CC supports two related instruction set architectures for the
  3125. RS/6000 and PowerPC.  The @dfn{POWER} instruction set are those
  3126. instructions supported by the @samp{rios} chip set used in the original
  3127. RS/6000 systems and the @dfn{PowerPC} instruction set is the
  3128. architecture of the Motorola MPC6xx microprocessors.  The PowerPC
  3129. architecture defines 64-bit instructions, but they are not supported by
  3130. any current processors.
  3131.  
  3132. Neither architecture is a subset of the other.  However there is a
  3133. large common subset of instructions supported by both.  An MQ
  3134. register is included in processors supporting the POWER architecture.
  3135.  
  3136. You use these options to specify which instructions are available on the
  3137. processor you are using.  The default value of these options is
  3138. determined when configuring GNU CC.  Specifying the
  3139. @samp{-mcpu=@var{cpu_type}} overrides the specification of these
  3140. options.  We recommend you use that option rather than these.
  3141.  
  3142. The @samp{-mpower} option allows GNU CC to generate instructions that
  3143. are found only in the POWER architecture and to use the MQ register.
  3144. Specifying @samp{-mpower2} implies @samp{-power} and also allows GNU CC
  3145. to generate instructions that are present in the POWER2 architecture but
  3146. not the original POWER architecture.
  3147.  
  3148. The @samp{-mpowerpc} option allows GNU CC to generate instructions that
  3149. are found only in the 32-bit subset of the PowerPC architecture.
  3150. Specifying @samp{-mpowerpc-gpopt} implies @samp{-mpowerpc} and also allows
  3151. GNU CC to use the optional PowerPC architecture instructions in the
  3152. General Purpose group, including floating-point square root.  Specifying
  3153. @samp{-mpowerpc-gfxopt} implies @samp{-mpowerpc} and also allows GNU CC to
  3154. use the optional PowerPC architecture instructions in the Graphics
  3155. group, including floating-point select.
  3156.  
  3157. If you specify both @samp{-mno-power} and @samp{-mno-powerpc}, GNU CC
  3158. will use only the instructions in the common subset of both
  3159. architectures plus some special AIX common-mode calls, and will not use
  3160. the MQ register.  Specifying both @samp{-mpower} and @samp{-mpowerpc}
  3161. permits GNU CC to use any instruction from either architecture and to
  3162. allow use of the MQ register; specify this for the Motorola MPC601.
  3163.  
  3164. @item -mnew-mnemonics
  3165. @itemx -mold-mnemonics
  3166. @kindex -mnew-mnemonics
  3167. @kindex -mold-mnemonics
  3168. Select which mnemonics to use in the generated assembler code.
  3169. @samp{-mnew-mnemonics} requests output that uses the assembler mnemonics
  3170. defined for the PowerPC architecture, while @samp{-mold-mnemonics}
  3171. requests the assembler mnemonics defined for the POWER architecture.
  3172. Instructions defined in only one architecture have only one mnemonic;
  3173. GNU CC uses that mnemonic irrespective of which of thse options is
  3174. specified.
  3175.  
  3176. PowerPC assemblers support both the old and new mnemonics, as will later
  3177. POWER assemblers.  Current POWER assemblers only support the old
  3178. mnemonics.  Specify @samp{-mnew-mnemonics} if you have an assembler that
  3179. supports them, otherwise specify @samp{-mold-mnemonics}.
  3180.  
  3181. The default value of these options depends on how GNU CC was configured.
  3182. Specifing @samp{-mcpu=@var{cpu_type}} sometimes overrides the value of
  3183. these option.  Unless you are building a cross-compiler, you should
  3184. normally not specify either @samp{-mnew-mnemonics} or
  3185. @samp{-mold-mnemonics}, but should instead accept the default.
  3186.  
  3187. @item -mcpu=@var{cpu_type}
  3188. Set architecture type, register usage, choice of mnemonics, and
  3189. instruction scheduling parameters for machine type @var{cpu_type}.  By
  3190. default, @var{cpu_type} is the target system defined when GNU CC was
  3191. configured.  Supported values for @var{cpu_type} are @samp{rios1},
  3192. @samp{rios2}, @samp{rsc}, @samp{601}, @samp{603}, @samp{604},
  3193. @samp{power}, @samp{powerpc}, and @samp{common}.  @samp{-mcpu=power} and
  3194. @samp{-mcpu=powerpc} specify generic POWER and pure PowerPC (i.e., not
  3195. MPC601) architecture machine types, with an appropriate, generic
  3196. processor model assumed for scheduling purposes.@refill
  3197.  
  3198. Specifying @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc}, or
  3199. @samp{-mcpu=power} enables the @samp{-mpower} option and disables the
  3200. @samp{-mpowerpc} option; @samp{-mcpu=601} enables both the
  3201. @samp{-mpower} and @samp{-mpowerpc} options; @samp{-mcpu=603},
  3202. @samp{-mcpu=604}, and @samp{-mcpu=powerpc} enable the @samp{-mpowerpc}
  3203. option and disable the @samp{-mpower} option; @samp{-mcpu=common}
  3204. disables both the @samp{-mpower} and @samp{-mpowerpc} options.@refill
  3205.  
  3206. To generate code that will operate on all members of the RS/6000 and
  3207. PowerPC families, specify @samp{-mcpu=common}.  In that case, GNU CC
  3208. will use only the instructions in the common subset of both
  3209. architectures plus some special AIX common-mode calls, and will not use
  3210. the MQ register.  GNU CC assumes a generic processor model for scheduling
  3211. purposes.
  3212.  
  3213. Specifying @samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc}, or
  3214. @samp{-mcpu=power} also disables the @samp{new-mnemonics} option.
  3215. Specifying @samp{-mcpu=601}, @samp{-mcpu=603}, @samp{-mcpu=604}, or
  3216. @samp{-mcpu=powerpc} also enables the @samp{new-mnemonics}
  3217. option.@refill
  3218.  
  3219. @item -mfull-toc
  3220. @itemx -mno-fp-in-toc
  3221. @itemx -mno-sum-in-toc
  3222. @itemx -mminimal-toc
  3223. Modify generation of the TOC (Table Of Contents), which is created for
  3224. every executable file.  The @samp{-mfull-toc} option is selected by
  3225. default.  In that case, GNU CC will allocate at least one TOC entry for
  3226. each unique non-automatic variable reference in your program.  GNU CC
  3227. will also place floating-point constants in the TOC.  However, only
  3228. 16,384 entries are available in the TOC.
  3229.  
  3230. If you receive a linker error message that saying you have overflowed
  3231. the available TOC space, you can reduce the amount of TOC space used
  3232. with the @samp{-mno-fp-in-toc} and @samp{-mno-sum-in-toc} options.
  3233. @samp{-mno-fp-in-toc} prevents GNU CC from putting floating-point
  3234. constants in the TOC and @samp{-mno-sum-in-toc} forces GNU CC to
  3235. generate code to calculate the sum of an address and a constant at
  3236. run-time instead of putting that sum into the TOC.  You may specify one
  3237. or both of these options.  Each causes GNU CC to produce very slightly
  3238. slower and larger code at the expense of conserving TOC space.
  3239.  
  3240. If you still run out of space in the TOC even when you specify both of
  3241. these options, specify @samp{-mminimal-toc} instead.  This option causes
  3242. GNU CC to make only one TOC entry for every file.  When you specify this
  3243. option, GNU CC will produce code that is slower and larger but which
  3244. uses extremely little TOC space.  You may wish to use this option
  3245. only on files that contain less frequently executed code. @refill
  3246. @end table
  3247. @node RT Options
  3248. @subsection IBM RT Options
  3249. @cindex RT options
  3250. @cindex IBM RT options
  3251.  
  3252. These @samp{-m} options are defined for the IBM RT PC:
  3253.  
  3254. @table @code
  3255. @item -min-line-mul
  3256. Use an in-line code sequence for integer multiplies.  This is the
  3257. default.
  3258.  
  3259. @item -mcall-lib-mul
  3260. Call @code{lmul$$} for integer multiples.
  3261.  
  3262. @item -mfull-fp-blocks
  3263. Generate full-size floating point data blocks, including the minimum
  3264. amount of scratch space recommended by IBM.  This is the default.
  3265.  
  3266. @item -mminimum-fp-blocks
  3267. Do not include extra scratch space in floating point data blocks.  This
  3268. results in smaller code, but slower execution, since scratch space must
  3269. be allocated dynamically.
  3270.  
  3271. @cindex @file{varargs.h} and RT PC
  3272. @cindex @file{stdarg.h} and RT PC
  3273. @item -mfp-arg-in-fpregs
  3274. Use a calling sequence incompatible with the IBM calling convention in
  3275. which floating point arguments are passed in floating point registers.
  3276. Note that @code{varargs.h} and @code{stdargs.h} will not work with
  3277. floating point operands if this option is specified.
  3278.  
  3279. @item -mfp-arg-in-gregs
  3280. Use the normal calling convention for floating point arguments.  This is
  3281. the default.
  3282.  
  3283. @item -mhc-struct-return
  3284. Return structures of more than one word in memory, rather than in a
  3285. register.  This provides compatibility with the MetaWare HighC (hc)
  3286. compiler.  Use the option @samp{-fpcc-struct-return} for compatibility
  3287. with the Portable C Compiler (pcc).
  3288.  
  3289. @item -mnohc-struct-return
  3290. Return some structures of more than one word in registers, when
  3291. convenient.  This is the default.  For compatibility with the
  3292. IBM-supplied compilers, use the option @samp{-fpcc-struct-return} or the
  3293. option @samp{-mhc-struct-return}.
  3294. @end table
  3295.  
  3296. @node MIPS Options
  3297. @subsection MIPS Options
  3298. @cindex MIPS options
  3299.  
  3300. These @samp{-m} options are defined for the MIPS family of computers:
  3301.  
  3302. @table @code
  3303. @item -mcpu=@var{cpu type}
  3304. Assume the defaults for the machine type @var{cpu type} when scheduling
  3305. instructions.  The choices for @var{cpu type} are @samp{r2000}, @samp{r3000},
  3306. @samp{r4000}, @samp{r4400}, @samp{r4600}, and @samp{r6000}.  While picking a
  3307. specific @var{cpu type} will schedule things appropriately for that
  3308. particular chip, the compiler will not generate any code that does not
  3309. meet level 1 of the MIPS ISA (instruction set architecture) without
  3310. the @samp{-mips2} or @samp{-mips3} switches being used.
  3311.  
  3312. @item -mips1
  3313. Issue instructions from level 1 of the MIPS ISA.  This is the default.
  3314. @samp{r3000} is the default @var{cpu type} at this ISA level.
  3315.  
  3316. @item -mips2
  3317. Issue instructions from level 2 of the MIPS ISA (branch likely, square
  3318. root instructions).  @samp{r6000} is the default @var{cpu type} at this
  3319. ISA level.
  3320.  
  3321. @item -mips3
  3322. Issue instructions from level 3 of the MIPS ISA (64 bit instructions).
  3323. @samp{r4000} is the default @var{cpu type} at this ISA level.
  3324. This option does not change the sizes of any of the C data types.
  3325.  
  3326. @item -mfp32
  3327. Assume that 32 32-bit floating point registers are available.  This is
  3328. the default.
  3329.  
  3330. @item -mfp64
  3331. Assume that 32 64-bit floating point registers are available.  This is
  3332. the default when the @samp{-mips3} option is used.
  3333.  
  3334. @item -mgp32
  3335. Assume that 32 32-bit general purpose registers are available.  This is
  3336. the default.
  3337.  
  3338. @item -mgp64
  3339. Assume that 32 64-bit general purpose registers are available.  This is
  3340. the default when the @samp{-mips3} option is used.
  3341.  
  3342. @item -mint64
  3343. Types long, int, and pointer are 64 bits.  This works only if @samp{-mips3}
  3344. is also specified.
  3345.  
  3346. @item -mlong64
  3347. Types long and pointer are 64 bits, and type int is 32 bits.
  3348. This works only if @samp{-mips3} is also specified.
  3349.  
  3350. @item -mmips-as
  3351. Generate code for the MIPS assembler, and invoke @file{mips-tfile} to
  3352. add normal debug information.  This is the default for all
  3353. platforms except for the OSF/1 reference platform, using the OSF/rose
  3354. object format.  If the either of the @samp{-gstabs} or @samp{-gstabs+}
  3355. switches are used, the @file{mips-tfile} program will encapsulate the
  3356. stabs within MIPS ECOFF.
  3357.  
  3358. @item -mgas
  3359. Generate code for the GNU assembler.  This is the default on the OSF/1
  3360. reference platform, using the OSF/rose object format.
  3361.  
  3362. @item -mrnames
  3363. @itemx -mno-rnames
  3364. The @samp{-mrnames} switch says to output code using the MIPS software
  3365. names for the registers, instead of the hardware names (ie, @var{a0}
  3366. instead of @var{$4}).  The only known assembler that supports this option
  3367. is the Algorithmics assembler.
  3368.  
  3369. @item -mgpopt
  3370. @itemx -mno-gpopt
  3371. The @samp{-mgpopt} switch says to write all of the data declarations
  3372. before the instructions in the text section, this allows the MIPS
  3373. assembler to generate one word memory references instead of using two
  3374. words for short global or static data items.  This is on by default if
  3375. optimization is selected.
  3376.  
  3377. @item -mstats
  3378. @itemx -mno-stats
  3379. For each non-inline function processed, the @samp{-mstats} switch
  3380. causes the compiler to emit one line to the standard error file to
  3381. print statistics about the program (number of registers saved, stack
  3382. size, etc.).
  3383.  
  3384. @item -mmemcpy
  3385. @itemx -mno-memcpy
  3386. The @samp{-mmemcpy} switch makes all block moves call the appropriate
  3387. string function (@samp{memcpy} or @samp{bcopy}) instead of possibly
  3388. generating inline code.
  3389.  
  3390. @item -mmips-tfile
  3391. @itemx -mno-mips-tfile
  3392. The @samp{-mno-mips-tfile} switch causes the compiler not
  3393. postprocess the object file with the @file{mips-tfile} program,
  3394. after the MIPS assembler has generated it to add debug support.  If
  3395. @file{mips-tfile} is not run, then no local variables will be
  3396. available to the debugger.  In addition, @file{stage2} and
  3397. @file{stage3} objects will have the temporary file names passed to the
  3398. assembler embedded in the object file, which means the objects will
  3399. not compare the same.  The @samp{-mno-mips-tfile} switch should only
  3400. be used when there are bugs in the @file{mips-tfile} program that
  3401. prevents compilation.
  3402.  
  3403. @item -msoft-float
  3404. Generate output containing library calls for floating point.
  3405. @strong{Warning:} the requisite libraries are not part of GNU CC.
  3406. Normally the facilities of the machine's usual C compiler are used, but
  3407. this can't be done directly in cross-compilation.  You must make your
  3408. own arrangements to provide suitable library functions for
  3409. cross-compilation.
  3410.  
  3411. @item -mhard-float
  3412. Generate output containing floating point instructions.  This is the
  3413. default if you use the unmodified sources.
  3414.  
  3415. @item -mabicalls
  3416. @itemx -mno-abicalls
  3417. Emit (or do not emit) the pseudo operations @samp{.abicalls},
  3418. @samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for
  3419. position independent code.
  3420.  
  3421. @item -mlong-calls
  3422. @itemx -mno-long-calls
  3423. Do all calls with the @samp{JALR} instruction, which requires
  3424. loading up a function's address into a register before the call.
  3425. You need to use this switch, if you call outside of the current
  3426. 512 megabyte segment to functions that are not through pointers.
  3427.  
  3428. @item -mhalf-pic
  3429. @itemx -mno-half-pic
  3430. Put pointers to extern references into the data section and load them
  3431. up, rather than put the references in the text section.
  3432.  
  3433. @item -membedded-pic
  3434. @itemx -mno-embedded-pic
  3435. Generate PIC code suitable for some embedded systems.  All calls are made
  3436. using PC relative address, and all data is addressed using the $gp register.
  3437. This requires GNU as and GNU ld which do most of the work.
  3438.  
  3439. @item -membedded-data
  3440. @itemx -mno-embedded-data
  3441. Allocate variables to the read-only data section first if possible, then
  3442. next in the small data section if possible, otherwise in data.  This gives
  3443. slightly slower code than the default, but reduces the amount of RAM required
  3444. when executing, and thus may be preferred for some embedded systems.
  3445.  
  3446. @item -G @var{num}
  3447. @cindex smaller data references (MIPS)
  3448. @cindex gp-relative references (MIPS)
  3449. Put global and static items less than or equal to @var{num} bytes into
  3450. the small data or bss sections instead of the normal data or bss
  3451. section.  This allows the assembler to emit one word memory reference
  3452. instructions based on the global pointer (@var{gp} or @var{$28}),
  3453. instead of the normal two words used.  By default, @var{num} is 8 when
  3454. the MIPS assembler is used, and 0 when the GNU assembler is used.  The
  3455. @samp{-G @var{num}} switch is also passed to the assembler and linker.
  3456. All modules should be compiled with the same @samp{-G @var{num}}
  3457. value.
  3458.  
  3459. @item -nocpp
  3460. Tell the MIPS assembler to not run it's preprocessor over user
  3461. assembler files (with a @samp{.s} suffix) when assembling them.
  3462. @end table
  3463.  
  3464. @ifset INTERNALS
  3465. These options are defined by the macro
  3466. @code{TARGET_SWITCHES} in the machine description.  The default for the
  3467. options is also defined by that macro, which enables you to change the
  3468. defaults.
  3469. @end ifset
  3470.  
  3471. @node i386 Options
  3472. @subsection Intel 386 Options
  3473. @cindex i386 Options
  3474. @cindex Intel 386 Options
  3475.  
  3476. These @samp{-m} options are defined for the i386 family of computers:
  3477.  
  3478. @table @code
  3479. @item -m486
  3480. @itemx -mno-486
  3481. Control whether or not code is optimized for a 486 instead of an
  3482. 386.  Code generated for an 486 will run on a 386 and vice versa.
  3483.  
  3484. @item -mieee-fp
  3485. @itemx -m-no-ieee-fp
  3486. Control whether or not the compiler uses IEEE floating point
  3487. comparisons.  These handle correctly the case where the result of a
  3488. comparison is unordered.
  3489.  
  3490. @item -msoft-float
  3491. Generate output containing library calls for floating point.
  3492. @strong{Warning:} the requisite libraries are not part of GNU CC.
  3493. Normally the facilities of the machine's usual C compiler are used, but
  3494. this can't be done directly in cross-compilation.  You must make your
  3495. own arrangements to provide suitable library functions for
  3496. cross-compilation.
  3497.  
  3498. On machines where a function returns floating point results in the 80387
  3499. register stack, some floating point opcodes may be emitted even if
  3500. @samp{-msoft-float} is used.
  3501.  
  3502. @item -mno-fp-ret-in-387
  3503. Do not use the FPU registers for return values of functions.
  3504.  
  3505. The usual calling convention has functions return values of types
  3506. @code{float} and @code{double} in an FPU register, even if there
  3507. is no FPU.  The idea is that the operating system should emulate
  3508. an FPU.
  3509.  
  3510. The option @samp{-mno-fp-ret-in-387} causes such values to be returned
  3511. in ordinary CPU registers instead.
  3512.  
  3513. @item -mno-fancy-math-387
  3514. Some 387 emulators do not support the @code{sin}, @code{cos} and
  3515. @code{sqrt} instructions for the 387.  Specify this option to avoid
  3516. generating those instructions. This option is the default on FreeBSD.
  3517. As of revision 2.6.1, these instructions are not generated unless you
  3518. also use the @samp{-ffast-math} switch.
  3519.  
  3520. @item -msvr3-shlib
  3521. @itemx -mno-svr3-shlib
  3522. Control whether GNU CC places uninitialized locals into @code{bss} or
  3523. @code{data}.  @samp{-msvr3-shlib} places these locals into @code{bss}.
  3524. These options are meaningful only on System V Release 3.
  3525.  
  3526. @item -mno-wide-multiply
  3527. @itemx -mwide-multiply
  3528. Control whether GNU CC uses the @code{mul} and @code{imul} that produce
  3529. 64 bit results in @code{eax:edx} from 32 bit operands to do @code{long
  3530. long} multiplies and 32-bit division by constants.
  3531.  
  3532. @item -mreg-alloc=@var{regs}
  3533. Control the default allocation order of integer registers.  The
  3534. string @var{regs} is a series of letters specifing a register.  The
  3535. supported letters are: @code{a} allocate EAX; @code{b} allocate EBX;
  3536. @code{c} allocate ECX; @code{d} allocate EDX; @code{S} allocate ESI;
  3537. @code{D} allocate EDI; @code{B} allocate EBP.
  3538. @end table
  3539.  
  3540. @node HPPA Options
  3541. @subsection HPPA Options
  3542. @cindex HPPA Options
  3543.  
  3544. These @samp{-m} options are defined for the HPPA family of computers:
  3545.  
  3546. @table @code
  3547. @item -mpa-risc-1-0
  3548. Generate code for a PA 1.0 processor.
  3549.  
  3550. @item -mpa-risc-1-1
  3551. Generate code for a PA 1.1 processor.
  3552.  
  3553. @item -mjump-in-delay
  3554. Fill delay slots of function calls with unconditional jump instructions
  3555. by modifying the return pointer for the function call to be the target
  3556. of the conditional jump.
  3557.  
  3558. @item -mlong-calls
  3559. Generate code which allows calls to functions greater than 256k away from
  3560. the caller when the caller and callee are in the same source file.  Do
  3561. not turn this option on unless code refuses to link with "branch out of
  3562. range errors" from the linker.
  3563.  
  3564. @item -mdisable-fpregs
  3565. Prevent floating point registers from being used in any manner.  This is
  3566. necessary for compiling kernels which perform lazy context switching of
  3567. floating point registers.  If you use this option and attempt to perform
  3568. floating point operations, the compiler will abort.
  3569.  
  3570. @item -mdisable-indexing
  3571. Prevent the compiler from using indexing address modes.  This avoids some
  3572. rather obscure problems when compiling MIG generated code under MACH.
  3573.  
  3574. @item -mportable-runtime
  3575. Use the portable calling conventions proposed by HP for ELF systems.  Note
  3576. this option also enables @samp{-mlong-calls}.
  3577.  
  3578. @item -mgas
  3579. Enable the use of assembler directives only GAS understands.
  3580. @end table
  3581.  
  3582. @node Intel 960 Options
  3583. @subsection Intel 960 Options
  3584.  
  3585. These @samp{-m} options are defined for the Intel 960 implementations:
  3586.  
  3587. @table @code
  3588. @item -m@var{cpu type}
  3589. Assume the defaults for the machine type @var{cpu type} for some of
  3590. the other options, including instruction scheduling, floating point
  3591. support, and addressing modes.  The choices for @var{cpu type} are
  3592. @samp{ka}, @samp{kb}, @samp{mc}, @samp{ca}, @samp{cf},
  3593. @samp{sa}, and @samp{sb}.
  3594. The default is
  3595. @samp{kb}.
  3596.  
  3597. @item -mnumerics
  3598. @itemx -msoft-float
  3599. The @samp{-mnumerics} option indicates that the processor does support
  3600. floating-point instructions.  The @samp{-msoft-float} option indicates
  3601. that floating-point support should not be assumed.
  3602.  
  3603. @item -mleaf-procedures
  3604. @itemx -mno-leaf-procedures
  3605. Do (or do not) attempt to alter leaf procedures to be callable with the
  3606. @code{bal} instruction as well as @code{call}.  This will result in more
  3607. efficient code for explicit calls when the @code{bal} instruction can be
  3608. substituted by the assembler or linker, but less efficient code in other
  3609. cases, such as calls via function pointers, or using a linker that doesn't
  3610. support this optimization.
  3611.  
  3612. @item -mtail-call
  3613. @itemx -mno-tail-call
  3614. Do (or do not) make additional attempts (beyond those of the
  3615. machine-independent portions of the compiler) to optimize tail-recursive
  3616. calls into branches.  You may not want to do this because the detection of
  3617. cases where this is not valid is not totally complete.  The default is
  3618. @samp{-mno-tail-call}.
  3619.  
  3620. @item -mcomplex-addr
  3621. @itemx -mno-complex-addr
  3622. Assume (or do not assume) that the use of a complex addressing mode is a
  3623. win on this implementation of the i960.  Complex addressing modes may not
  3624. be worthwhile on the K-series, but they definitely are on the C-series.
  3625. The default is currently @samp{-mcomplex-addr} for all processors except
  3626. the CB and CC.
  3627.  
  3628. @item -mcode-align
  3629. @itemx -mno-code-align
  3630. Align code to 8-byte boundaries for faster fetching (or don't bother).
  3631. Currently turned on by default for C-series implementations only.
  3632.  
  3633. @ignore
  3634. @item -mclean-linkage
  3635. @itemx -mno-clean-linkage
  3636. These options are not fully implemented.
  3637. @end ignore
  3638.  
  3639. @item -mic-compat
  3640. @itemx -mic2.0-compat
  3641. @itemx -mic3.0-compat
  3642. Enable compatibility with iC960 v2.0 or v3.0.
  3643.  
  3644. @item -masm-compat
  3645. @itemx -mintel-asm
  3646. Enable compatibility with the iC960 assembler.
  3647.  
  3648. @item -mstrict-align
  3649. @itemx -mno-strict-align
  3650. Do not permit (do permit) unaligned accesses.
  3651.  
  3652. @item -mold-align
  3653. Enable structure-alignment compatibility with Intel's gcc release version
  3654. 1.3 (based on gcc 1.37).  Currently this is buggy in that @samp{#pragma
  3655. align 1} is always assumed as well, and cannot be turned off.
  3656. @end table
  3657.  
  3658. @node DEC Alpha Options
  3659. @subsection DEC Alpha Options
  3660.  
  3661. These @samp{-m} options are defined for the DEC Alpha implementations:
  3662.  
  3663. @table @code
  3664. @item -mno-soft-float
  3665. @itemx -msoft-float
  3666. Use (do not use) the hardware floating-point instructions for
  3667. floating-point operations.  When @code{-msoft-float} is specified,
  3668. functions in @file{libgcc1.c} will be used to perform floating-point
  3669. operations.  Unless they are replaced by routines that emulate the
  3670. floating-point operations, or compiled in such a way as to call such
  3671. emulations routines, these routines will issue floating-point
  3672. operations.   If you are compiling for an Alpha without floating-point
  3673. operations, you must ensure that the library is built so as not to call
  3674. them.
  3675.  
  3676. Note that Alpha implementations without floating-point operations are
  3677. required to have floating-point registers.
  3678.  
  3679. @item -mfp-reg
  3680. @itemx -mno-fp-regs
  3681. Generate code that uses (does not use) the floating-point register set.
  3682. @code{-mno-fp-regs} implies @code{-msoft-float}.  If the floating-point
  3683. register set is not used, floating point operands are passed in integer
  3684. registers as if they were integers and floating-point results are passed
  3685. in $0 instead of $f0.  This is a non-standard calling sequence, so any
  3686. function with a floating-point argument or return value called by code
  3687. compiled with @code{-mno-fp-regs} must also be compiled with that
  3688. option.
  3689.  
  3690. A typical use of this option is building a kernel that does not use,
  3691. and hence need not save and restore, any floating-point registers.
  3692. @end table
  3693.  
  3694. @node Clipper Options
  3695. @subsection Clipper Options
  3696.  
  3697. These @samp{-m} options are defined for the Clipper implementations:
  3698.  
  3699. @table @code
  3700. @item -mc300
  3701. Produce code for a C300 Clipper processor. This is the default.
  3702.  
  3703. @itemx -mc400
  3704. Produce code for a C400 Clipper processor i.e. use floting point
  3705. registers f8..f15.
  3706. @end table
  3707.  
  3708. @node H8/300 Options
  3709. @subsection H8/300 Options
  3710.  
  3711. These @samp{-m} options are defined for the H8/300 implementations:
  3712.  
  3713. @table @code
  3714. @item -mrelax
  3715. Shorten some address references at link time, when possible; uses the
  3716. linker option @samp{-relax}.  @xref{H8/300,, @code{ld} and the H8/300,
  3717. ld.info, Using ld}, for a fuller description.
  3718.  
  3719. @item -mh
  3720. Generate code for the H8/300H.
  3721. @end table
  3722.  
  3723. @node System V Options
  3724. @subsection Options for System V
  3725.  
  3726. These additional options are available on System V Release 4 for
  3727. compatibility with other compilers on those systems:
  3728.  
  3729. @table @code
  3730. @ignore
  3731. This should say *what the option does* and only then say
  3732. "For compatibility only..."
  3733. @item -G
  3734. On SVr4 systems, @code{gcc} accepts the option @samp{-G} (and passes
  3735. it to the system linker), for compatibility with other compilers.
  3736. However, we suggest you use @samp{-symbolic} or @samp{-shared} as
  3737. appropriate, instead of supplying linker options on the @code{gcc}
  3738. command line.
  3739. @end ignore
  3740.  
  3741. @item -Qy
  3742. Identify the versions of each tool used by the compiler, in a
  3743. @code{.ident} assembler directive in the output.
  3744.  
  3745. @item -Qn
  3746. Refrain from adding @code{.ident} directives to the output file (this is
  3747. the default).
  3748.  
  3749. @item -YP,@var{dirs}
  3750. Search the directories @var{dirs}, and no others, for libraries
  3751. specified with @samp{-l}.
  3752.  
  3753. @item -Ym,@var{dir}
  3754. Look in the directory @var{dir} to find the M4 preprocessor.
  3755. The assembler uses this option.
  3756. @c This is supposed to go with a -Yd for predefined M4 macro files, but 
  3757. @c the generic assembler that comes with Solaris takes just -Ym.
  3758. @end table
  3759.  
  3760. @node Code Gen Options
  3761. @section Options for Code Generation Conventions
  3762. @cindex code generation conventions
  3763. @cindex options, code generation 
  3764. @cindex run-time options
  3765.  
  3766. These machine-independent options control the interface conventions
  3767. used in code generation.
  3768.  
  3769. Most of them have both positive and negative forms; the negative form
  3770. of @samp{-ffoo} would be @samp{-fno-foo}.  In the table below, only
  3771. one of the forms is listed---the one which is not the default.  You
  3772. can figure out the other form by either removing @samp{no-} or adding
  3773. it.
  3774.  
  3775. @table @code
  3776. @item -fpcc-struct-return
  3777. Return ``short'' @code{struct} and @code{union} values in memory like
  3778. longer ones, rather than in registers.  This convention is less
  3779. efficient, but it has the advantage of allowing intercallability between
  3780. GNU CC-compiled files and files compiled with other compilers.
  3781.  
  3782. The precise convention for returning structures in memory depends
  3783. on the target configuration macros.
  3784.  
  3785. Short structures and unions are those whose size and alignment match
  3786. that of some integer type.
  3787.  
  3788. @item -freg-struct-return
  3789. Use the convention that @code{struct} and @code{union} values are
  3790. returned in registers when possible.  This is more efficient for small
  3791. structures than @samp{-fpcc-struct-return}.
  3792.  
  3793. If you specify neither @samp{-fpcc-struct-return} nor its contrary
  3794. @samp{-freg-struct-return}, GNU CC defaults to whichever convention is
  3795. standard for the target.  If there is no standard convention, GNU CC
  3796. defaults to @samp{-fpcc-struct-return}, except on targets where GNU CC
  3797. is the principal compiler.  In those cases, we can choose the standard,
  3798. and we chose the more efficient register return alternative.
  3799.  
  3800. @item -fshort-enums
  3801. Allocate to an @code{enum} type only as many bytes as it needs for the
  3802. declared range of possible values.  Specifically, the @code{enum} type
  3803. will be equivalent to the smallest integer type which has enough room.
  3804.  
  3805. @item -fshort-double
  3806. Use the same size for @code{double} as for @code{float}.
  3807.  
  3808. @item -fshared-data
  3809. Requests that the data and non-@code{const} variables of this
  3810. compilation be shared data rather than private data.  The distinction
  3811. makes sense only on certain operating systems, where shared data is
  3812. shared between processes running the same program, while private data
  3813. exists in one copy per process.
  3814.  
  3815. @item -fno-common
  3816. Allocate even uninitialized global variables in the bss section of the
  3817. object file, rather than generating them as common blocks.  This has the
  3818. effect that if the same variable is declared (without @code{extern}) in
  3819. two different compilations, you will get an error when you link them.
  3820. The only reason this might be useful is if you wish to verify that the
  3821. program will work on other systems which always work this way.
  3822.  
  3823. @item -fno-ident
  3824. Ignore the @samp{#ident} directive.
  3825.  
  3826. @item -fno-gnu-linker
  3827. Do not output global initializations (such as C++ constructors and
  3828. destructors) in the form used by the GNU linker (on systems where the GNU
  3829. linker is the standard method of handling them).  Use this option when
  3830. you want to use a non-GNU linker, which also requires using the
  3831. @code{collect2} program to make sure the system linker includes
  3832. constructors and destructors.  (@code{collect2} is included in the GNU CC
  3833. distribution.)  For systems which @emph{must} use @code{collect2}, the
  3834. compiler driver @code{gcc} is configured to do this automatically.
  3835.  
  3836. @item -finhibit-size-directive
  3837. Don't output a @code{.size} assembler directive, or anything else that
  3838. would cause trouble if the function is split in the middle, and the 
  3839. two halves are placed at locations far apart in memory.  This option is
  3840. used when compiling @file{crtstuff.c}; you should not need to use it
  3841. for anything else.
  3842.  
  3843. @item -fverbose-asm
  3844. Put extra commentary information in the generated assembly code to
  3845. make it more readable.  This option is generally only of use to those
  3846. who actually need to read the generated assembly code (perhaps while
  3847. debugging the compiler itself).
  3848.  
  3849. @item -fvolatile
  3850. Consider all memory references through pointers to be volatile.
  3851.  
  3852. @item -fvolatile-global
  3853. Consider all memory references to extern and global data items to
  3854. be volatile.
  3855.  
  3856. @item -fpic
  3857. @cindex global offset table
  3858. @cindex PIC
  3859. Generate position-independent code (PIC) suitable for use in a shared
  3860. library, if supported for the target machine.  Such code accesses all
  3861. constant addresses through a global offset table (GOT).  If the GOT size
  3862. for the linked executable exceeds a machine-specific maximum size, you
  3863. get an error message from the linker indicating that @samp{-fpic} does
  3864. not work; in that case, recompile with @samp{-fPIC} instead.  (These
  3865. maximums are 16k on the m88k, 8k on the Sparc, and 32k on the m68k and
  3866. RS/6000.  The 386 has no such limit.)
  3867.  
  3868. Position-independent code requires special support, and therefore works
  3869. only on certain machines.  For the 386, GNU CC supports PIC for System V
  3870. but not for the Sun 386i.  Code generated for the IBM RS/6000 is always
  3871. position-independent.
  3872.  
  3873. The GNU assembler does not fully support PIC.  Currently, you must use
  3874. some other assembler in order for PIC to work.  We would welcome
  3875. volunteers to upgrade GAS to handle this; the first part of the job is
  3876. to figure out what the assembler must do differently.
  3877.  
  3878. @item -fPIC
  3879. If supported for the target machine, emit position-independent code,
  3880. suitable for dynamic linking and avoiding any limit on the size of the
  3881. global offset table.  This option makes a difference on the m68k, m88k
  3882. and the Sparc.
  3883.  
  3884. Position-independent code requires special support, and therefore works
  3885. only on certain machines.
  3886.  
  3887. @item -ffixed-@var{reg}
  3888. Treat the register named @var{reg} as a fixed register; generated code
  3889. should never refer to it (except perhaps as a stack pointer, frame
  3890. pointer or in some other fixed role).
  3891.  
  3892. @var{reg} must be the name of a register.  The register names accepted
  3893. are machine-specific and are defined in the @code{REGISTER_NAMES}
  3894. macro in the machine description macro file.
  3895.  
  3896. This flag does not have a negative form, because it specifies a
  3897. three-way choice.
  3898.  
  3899. @item -fcall-used-@var{reg}
  3900. Treat the register named @var{reg} as an allocatable register that is
  3901. clobbered by function calls.  It may be allocated for temporaries or
  3902. variables that do not live across a call.  Functions compiled this way
  3903. will not save and restore the register @var{reg}.
  3904.  
  3905. Use of this flag for a register that has a fixed pervasive role in the
  3906. machine's execution model, such as the stack pointer or frame pointer,
  3907. will produce disastrous results.
  3908.  
  3909. This flag does not have a negative form, because it specifies a
  3910. three-way choice.
  3911.  
  3912. @item -fcall-saved-@var{reg}
  3913. Treat the register named @var{reg} as an allocatable register saved by
  3914. functions.  It may be allocated even for temporaries or variables that
  3915. live across a call.  Functions compiled this way will save and restore
  3916. the register @var{reg} if they use it.
  3917.  
  3918. Use of this flag for a register that has a fixed pervasive role in the
  3919. machine's execution model, such as the stack pointer or frame pointer,
  3920. will produce disastrous results.
  3921.  
  3922. A different sort of disaster will result from the use of this flag for
  3923. a register in which function values may be returned.
  3924.  
  3925. This flag does not have a negative form, because it specifies a
  3926. three-way choice.
  3927.  
  3928. @item +e0
  3929. @itemx +e1
  3930. Control whether virtual function definitions in classes are used to
  3931. generate code, or only to define interfaces for their callers.  (C++
  3932. only).
  3933.  
  3934. These options are provided for compatibility with @code{cfront} 1.x
  3935. usage; the recommended alternative GNU C++ usage is in flux.  @xref{C++
  3936. Interface,,Declarations and Definitions in One Header}.
  3937.  
  3938. With @samp{+e0}, virtual function definitions in classes are declared
  3939. @code{extern}; the declaration is used only as an interface
  3940. specification, not to generate code for the virtual functions (in this
  3941. compilation).
  3942.  
  3943. With @samp{+e1}, G++ actually generates the code implementing virtual
  3944. functions defined in the code, and makes them publicly visible.
  3945. @end table
  3946.  
  3947. @node Environment Variables
  3948. @section Environment Variables Affecting GNU CC
  3949. @cindex environment variables
  3950.  
  3951. This section describes several environment variables that affect how GNU
  3952. CC operates.  They work by specifying directories or prefixes to use
  3953. when searching for various kinds of files.
  3954.  
  3955. @ifclear INTERNALS
  3956. Note that you can also specify places to search using options such as
  3957. @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}).  These
  3958. take precedence over places specified using environment variables, which
  3959. in turn take precedence over those specified by the configuration of GNU
  3960. CC. 
  3961. @end ifclear
  3962. @ifset INTERNALS
  3963. Note that you can also specify places to search using options such as
  3964. @samp{-B}, @samp{-I} and @samp{-L} (@pxref{Directory Options}).  These
  3965. take precedence over places specified using environment variables, which
  3966. in turn take precedence over those specified by the configuration of GNU
  3967. CC.  @xref{Driver}.
  3968. @end ifset
  3969.  
  3970. @table @code
  3971. @item TMPDIR
  3972. @findex TMPDIR
  3973. If @code{TMPDIR} is set, it specifies the directory to use for temporary
  3974. files.  GNU CC uses temporary files to hold the output of one stage of
  3975. compilation which is to be used as input to the next stage: for example,
  3976. the output of the preprocessor, which is the input to the compiler
  3977. proper.
  3978.  
  3979. @item GCC_EXEC_PREFIX
  3980. @findex GCC_EXEC_PREFIX
  3981. If @code{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
  3982. names of the subprograms executed by the compiler.  No slash is added
  3983. when this prefix is combined with the name of a subprogram, but you can
  3984. specify a prefix that ends with a slash if you wish.
  3985.  
  3986. If GNU CC cannot find the subprogram using the specified prefix, it
  3987. tries looking in the usual places for the subprogram.
  3988.  
  3989. The default value of @code{GCC_EXEC_PREFIX} is
  3990. @file{@var{prefix}/lib/gcc-lib/@var{machine}/@var{version}/} where
  3991. @var{prefix} is the value of @code{prefix} when you ran the
  3992. @file{configure} script and @var{machine} and @var{version} are the
  3993. configuration name and version number of GNU CC, respectively.
  3994.  
  3995. Other prefixes specified with @samp{-B} take precedence over this prefix.
  3996.  
  3997. This prefix is also used for finding files such as @file{crt0.o} that are
  3998. used for linking.
  3999.  
  4000. In addition, the prefix is used in an unusual way in finding the
  4001. directories to search for header files.  For each of the standard
  4002. directories whose name normally begins with @samp{/usr/local/lib/gcc-lib}
  4003. (more precisely, with the value of @code{GCC_INCLUDE_DIR}), GNU CC tries
  4004. replacing that beginning with the specified prefix to produce an
  4005. alternate directory name.  Thus, with @samp{-Bfoo/}, GNU CC will search
  4006. @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
  4007. These alternate directories are searched first; the standard directories
  4008. come next.
  4009.  
  4010. @item COMPILER_PATH
  4011. @findex COMPILER_PATH
  4012. The value of @code{COMPILER_PATH} is a colon-separated list of
  4013. directories, much like @code{PATH}.  GNU CC tries the directories thus
  4014. specified when searching for subprograms, if it can't find the
  4015. subprograms using @code{GCC_EXEC_PREFIX}.
  4016.  
  4017. @item LIBRARY_PATH
  4018. @findex LIBRARY_PATH
  4019. The value of @code{LIBRARY_PATH} is a colon-separated list of
  4020. directories, much like @code{PATH}.  GNU CC tries the directories thus
  4021. specified when searching for special linker files, if it can't find them
  4022. using @code{GCC_EXEC_PREFIX}.  Linking using GNU CC also uses these
  4023. directories when searching for ordinary libraries for the @samp{-l}
  4024. option (but directories specified with @samp{-L} come first).
  4025.  
  4026. @item C_INCLUDE_PATH
  4027. @itemx CPLUS_INCLUDE_PATH
  4028. @itemx OBJC_INCLUDE_PATH
  4029. @findex C_INCLUDE_PATH
  4030. @findex CPLUS_INCLUDE_PATH
  4031. @findex OBJC_INCLUDE_PATH
  4032. @c @itemx OBJCPLUS_INCLUDE_PATH
  4033. These environment variables pertain to particular languages.  Each
  4034. variable's value is a colon-separated list of directories, much like
  4035. @code{PATH}.  When GNU CC searches for header files, it tries the
  4036. directories listed in the variable for the language you are using, after
  4037. the directories specified with @samp{-I} but before the standard header
  4038. file directories.
  4039.  
  4040. @item DEPENDENCIES_OUTPUT
  4041. @findex DEPENDENCIES_OUTPUT
  4042. @cindex dependencies for make as output 
  4043. If this variable is set, its value specifies how to output dependencies
  4044. for Make based on the header files processed by the compiler.  This
  4045. output looks much like the output from the @samp{-M} option
  4046. (@pxref{Preprocessor Options}), but it goes to a separate file, and is
  4047. in addition to the usual results of compilation.
  4048.  
  4049. The value of @code{DEPENDENCIES_OUTPUT} can be just a file name, in
  4050. which case the Make rules are written to that file, guessing the target
  4051. name from the source file name.  Or the value can have the form
  4052. @samp{@var{file} @var{target}}, in which case the rules are written to
  4053. file @var{file} using @var{target} as the target name.
  4054. @end table
  4055.  
  4056. @node Running Protoize
  4057. @section Running Protoize
  4058.  
  4059. The program @code{protoize} is an optional part of GNU C.  You can use
  4060. it to add prototypes to a program, thus converting the program to ANSI
  4061. C in one respect.  The companion program @code{unprotoize} does the
  4062. reverse: it removes argument types from any prototypes that are found.
  4063.  
  4064. When you run these programs, you must specify a set of source files as
  4065. command line arguments.  The conversion programs start out by compiling
  4066. these files to see what functions they define.  The information gathered
  4067. about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
  4068.  
  4069. After scanning comes actual conversion.  The specified files are all
  4070. eligible to be converted; any files they include (whether sources or
  4071. just headers) are eligible as well.
  4072.  
  4073. But not all the eligible files are converted.  By default,
  4074. @code{protoize} and @code{unprotoize} convert only source and header
  4075. files in the current directory.  You can specify additional directories
  4076. whose files should be converted with the @samp{-d @var{directory}}
  4077. option.  You can also specify particular files to exclude with the
  4078. @samp{-x @var{file}} option.  A file is converted if it is eligible, its
  4079. directory name matches one of the specified directory names, and its
  4080. name within the directory has not been excluded.
  4081.  
  4082. Basic conversion with @code{protoize} consists of rewriting most
  4083. function definitions and function declarations to specify the types of
  4084. the arguments.  The only ones not rewritten are those for varargs
  4085. functions.
  4086.  
  4087. @code{protoize} optionally inserts prototype declarations at the
  4088. beginning of the source file, to make them available for any calls that
  4089. precede the function's definition.  Or it can insert prototype
  4090. declarations with block scope in the blocks where undeclared functions
  4091. are called.
  4092.  
  4093. Basic conversion with @code{unprotoize} consists of rewriting most
  4094. function declarations to remove any argument types, and rewriting
  4095. function definitions to the old-style pre-ANSI form.
  4096.  
  4097. Both conversion programs print a warning for any function declaration or
  4098. definition that they can't convert.  You can suppress these warnings
  4099. with @samp{-q}.
  4100.  
  4101. The output from @code{protoize} or @code{unprotoize} replaces the
  4102. original source file.  The original file is renamed to a name ending
  4103. with @samp{.save}.  If the @samp{.save} file already exists, then 
  4104. the source file is simply discarded.
  4105.  
  4106. @code{protoize} and @code{unprotoize} both depend on GNU CC itself to
  4107. scan the program and collect information about the functions it uses.
  4108. So neither of these programs will work until GNU CC is installed.
  4109.  
  4110. Here is a table of the options you can use with @code{protoize} and
  4111. @code{unprotoize}.  Each option works with both programs unless
  4112. otherwise stated.
  4113.  
  4114. @table @code
  4115. @item -B @var{directory}
  4116. Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
  4117. usual directory (normally @file{/usr/local/lib}).  This file contains
  4118. prototype information about standard system functions.  This option
  4119. applies only to @code{protoize}.
  4120.  
  4121. @item -c @var{compilation-options}
  4122. Use  @var{compilation-options} as the options when running @code{gcc} to
  4123. produce the @samp{.X} files.  The special option @samp{-aux-info} is
  4124. always passed in addition, to tell @code{gcc} to write a @samp{.X} file.
  4125.  
  4126. Note that the compilation options must be given as a single argument to
  4127. @code{protoize} or @code{unprotoize}.  If you want to specify several
  4128. @code{gcc} options, you must quote the entire set of compilation options
  4129. to make them a single word in the shell.
  4130.  
  4131. There are certain @code{gcc} arguments that you cannot use, because they
  4132. would produce the wrong kind of output.  These include @samp{-g},
  4133. @samp{-O}, @samp{-c}, @samp{-S}, and @samp{-o} If you include these in
  4134. the @var{compilation-options}, they are ignored.
  4135.  
  4136. @item -C
  4137. Rename files to end in @samp{.C} instead of @samp{.c}.
  4138. This is convenient if you are converting a C program to C++.
  4139. This option applies only to @code{protoize}.
  4140.  
  4141. @item -g
  4142. Add explicit global declarations.  This means inserting explicit
  4143. declarations at the beginning of each source file for each function
  4144. that is called in the file and was not declared.  These declarations
  4145. precede the first function definition that contains a call to an
  4146. undeclared function.  This option applies only to @code{protoize}.
  4147.  
  4148. @item -i @var{string}
  4149. Indent old-style parameter declarations with the string @var{string}.
  4150. This option applies only to @code{protoize}.
  4151.  
  4152. @code{unprotoize} converts prototyped function definitions to old-style
  4153. function definitions, where the arguments are declared between the
  4154. argument list and the initial @samp{@{}.  By default, @code{unprotoize}
  4155. uses five spaces as the indentation.  If you want to indent with just
  4156. one space instead, use @samp{-i " "}.
  4157.  
  4158. @item -k
  4159. Keep the @samp{.X} files.  Normally, they are deleted after conversion
  4160. is finished.
  4161.  
  4162. @item -l
  4163. Add explicit local declarations.  @code{protoize} with @samp{-l} inserts
  4164. a prototype declaration for each function in each block which calls the
  4165. function without any declaration.  This option applies only to
  4166. @code{protoize}.
  4167.  
  4168. @item -n
  4169. Make no real changes.  This mode just prints information about the conversions
  4170. that would have been done without @samp{-n}.
  4171.  
  4172. @item -N
  4173. Make no @samp{.save} files.  The original files are simply deleted.
  4174. Use this option with caution.
  4175.  
  4176. @item -p @var{program}
  4177. Use the program @var{program} as the compiler.  Normally, the name
  4178. @file{gcc} is used.
  4179.  
  4180. @item -q
  4181. Work quietly.  Most warnings are suppressed.
  4182.  
  4183. @item -v
  4184. Print the version number, just like @samp{-v} for @code{gcc}.
  4185. @end table
  4186.  
  4187. If you need special compiler options to compile one of your program's
  4188. source files, then you should generate that file's @samp{.X} file
  4189. specially, by running @code{gcc} on that source file with the
  4190. appropriate options and the option @samp{-aux-info}.  Then run
  4191. @code{protoize} on the entire set of files.  @code{protoize} will use
  4192. the existing @samp{.X} file because it is newer than the source file.
  4193. For example:
  4194.  
  4195. @example
  4196. gcc -Dfoo=bar file1.c -aux-info
  4197. protoize *.c
  4198. @end example
  4199.  
  4200. @noindent
  4201. You need to include the special files along with the rest in the
  4202. @code{protoize} command, even though their @samp{.X} files already
  4203. exist, because otherwise they won't get converted.
  4204.  
  4205. @xref{Protoize Caveats}, for more information on how to use
  4206. @code{protoize} successfully.
  4207.  
  4208.